Una lunga serie di modifiche per tenere conto della riorganizzazione della
[gapil.git] / fileunix.tex
index 6f9334d..782afc9 100644 (file)
@@ -992,13 +992,13 @@ tutta una serie di operazioni ausiliarie che 
 descriptor, che non riguardano la normale lettura e scrittura di dati, ma la
 gestione sia delle loro proprietà, che di tutta una serie di ulteriori
 funzionalità che il kernel può mettere a disposizione.\footnote{ad esempio si
-  gestiscono con questa funzione l'I/O asincrono (vedi
-  \secref{sec:file_asyncronous_io}) e il file locking\index{file!locking}
-  (vedi \secref{sec:file_locking}).}
+  gestiscono con questa funzione varie modalità di I/O asincrono (vedi
+  \secref{sec:file_asyncronous_operation}) e il file
+  locking\index{file!locking} (vedi \secref{sec:file_locking}).}
 
-Per queste operazioni di manipolazione e di controllo su proprietà e
-caratteristiche un file descriptor, viene usata la funzione \funcd{fcntl}, il
-cui prototipo è:
+Per queste operazioni di manipolazione e di controllo delle varie proprietà e
+caratteristiche di un file descriptor, viene usata la funzione \funcd{fcntl},
+il cui prototipo è:
 \begin{functions}
   \headdecl{unistd.h}
   \headdecl{fcntl.h}
@@ -1017,92 +1017,127 @@ cui prototipo 
   \end{errlist}}
 \end{functions}
 
-Il comportamento di questa funzione è determinato dal valore del comando
-\param{cmd} che le viene fornito; in \secref{sec:file_dup} abbiamo incontrato
-un esempio per la duplicazione dei file descriptor, una lista dei possibili
-valori è riportata di seguito:
+
+Il primo argomento della funzione è sempre il numero di file descriptor
+\var{fd} su cui si vuole operare. Il comportamento di questa funzione, il
+numero e il tipo degli argomenti, il valore di ritorno e gli eventuali errori
+sono determinati dal valore dell'argomento \param{cmd} che in sostanza
+corrisponde all'esecuzione di un determinato \textsl{comando}; in
+\secref{sec:file_dup} abbiamo incontrato un esempio dell'uso di \func{fcntl}
+per la duplicazione dei file descriptor, una lista di tutti i possibili valori
+per \var{cmd} è riportata di seguito:
 \begin{basedescript}{\desclabelwidth{2.0cm}}
 \item[\const{F\_DUPFD}] trova il primo file descriptor disponibile di valore
-  maggiore o uguale ad \param{arg} e ne fa una copia di \param{fd}. In caso di
-  successo ritorna il nuovo file descriptor. Gli errori possibili sono
-  \errcode{EINVAL} se \param{arg} è negativo o maggiore del massimo consentito
-  o \errcode{EMFILE} se il processo ha già raggiunto il massimo numero di
-  descrittori consentito.
+  maggiore o uguale ad \param{arg} e ne fa una copia di \param{fd}. Ritorna il
+  nuovo file descriptor in caso di successo e -1 in caso di errore. Gli errori
+  possibili sono \errcode{EINVAL} se \param{arg} è negativo o maggiore del
+  massimo consentito o \errcode{EMFILE} se il processo ha già raggiunto il
+  massimo numero di descrittori consentito.
 \item[\const{F\_SETFD}] imposta il valore del \textit{file descriptor flag} al
   valore specificato con \param{arg}. Al momento l'unico bit usato è quello di
   \textit{close-on-exec}\index{close-on-exec}, identificato dalla costante
   \const{FD\_CLOEXEC}, che serve a richiedere che il file venga chiuso nella
-  esecuzione di una \func{exec} (vedi \secref{sec:proc_exec}).
+  esecuzione di una \func{exec} (vedi \secref{sec:proc_exec}). Ritorna un
+  valore nullo in caso di successo e -1 in caso di errore.
 \item[\const{F\_GETFD}] ritorna il valore del \textit{file descriptor flag} di
-  \param{fd}, se \const{FD\_CLOEXEC} è impostato i file descriptor aperti
-  vengono chiusi attraverso una \func{exec} altrimenti (il comportamento
-  predefinito) restano aperti.
-\item[\const{F\_GETFL}] ritorna il valore del \textit{file status flag},
-  permette cioè di rileggere quei bit impostati da \func{open} all'apertura del
-  file che vengono memorizzati (quelli riportati nella prima e terza sezione
-  di \tabref{tab:file_open_flags}). 
+  \param{fd} o -1 in caso di errore; se \const{FD\_CLOEXEC} è impostato i file
+  descriptor aperti vengono chiusi attraverso una \func{exec} altrimenti (il
+  comportamento predefinito) restano aperti.
+\item[\const{F\_GETFL}] ritorna il valore del \textit{file status flag} in
+  caso di successo o -1 in caso di errore; permette cioè di rileggere quei bit
+  impostati da \func{open} all'apertura del file che vengono memorizzati
+  (quelli riportati nella prima e terza sezione di
+  \tabref{tab:file_open_flags}).
 \item[\const{F\_SETFL}] imposta il \textit{file status flag} al valore
-  specificato da \param{arg}, possono essere impostati solo i bit riportati
-  nella terza sezione di \tabref{tab:file_open_flags}.\footnote{la pagina di
-    manuale riporta come impostabili solo \const{O\_APPEND},
-    \const{O\_NONBLOCK} e \const{O\_ASYNC}.}
+  specificato da \param{arg}, ritorna un valore nullo in caso di successo o -1
+  in caso di errore. Possono essere impostati solo i bit riportati nella terza
+  sezione di \tabref{tab:file_open_flags}.\footnote{la pagina di manuale
+    riporta come impostabili solo \const{O\_APPEND}, \const{O\_NONBLOCK} e
+    \const{O\_ASYNC}.}
 \item[\const{F\_GETLK}] richiede un controllo sul file lock specificato da
-  \param{lock}, sovrascrivendo la struttura da esso puntata con il risultato
-  (questa funzionalità è trattata in dettaglio in
-  \secref{sec:file_posix_lock}).
+  \param{lock}, sovrascrivendo la struttura da esso puntata con il risultato,
+  ritorna un valore nullo in caso di successo o -1 in caso di errore.  Questa
+  funzionalità è trattata in dettaglio in \secref{sec:file_posix_lock}.
 \item[\const{F\_SETLK}] richiede o rilascia un file lock a seconda di quanto
   specificato nella struttura puntata da \param{lock}. Se il lock è tenuto da
   qualcun'altro ritorna immediatamente restituendo -1 e imposta \var{errno} a
-  \errcode{EACCES} o \errcode{EAGAIN} (questa funzionalità è trattata in
-  dettaglio in \secref{sec:file_posix_lock}).
+  \errcode{EACCES} o \errcode{EAGAIN}, in caso di successo ritorna un valore
+  nullo. Questa funzionalità è trattata in dettaglio in
+  \secref{sec:file_posix_lock}.
 \item[\const{F\_SETLKW}] identica a \const{F\_SETLK} eccetto per il fatto che
   la funzione non ritorna subito ma attende che il blocco sia rilasciato. Se
   l'attesa viene interrotta da un segnale la funzione restituisce -1 e imposta
-  \var{errno} a \errcode{EINTR} (questa funzionalità è trattata in dettaglio in
-  \secref{sec:file_posix_lock}).
+  \var{errno} a \errcode{EINTR}, in caso di successo ritorna un valore nullo.
+  Questa funzionalità è trattata in dettaglio in \secref{sec:file_posix_lock}.
 \item[\const{F\_GETOWN}] restituisce il \acr{pid} del processo o
   l'identificatore del process group\footnote{i \texttt{process group} sono
-    (vedi \secref{sec:sess_proc_group}) sono raggruppamenti di processi usati
-    nel controllo di sessione; a ciascuno di essi è associato un
-    identificatore (un numero positivo analogo al \acr{pid}).}  che è preposto
-  alla ricezione dei segnali \const{SIGIO} e \const{SIGURG} per gli eventi
-  associati al file descriptor \param{fd}. Nel caso di un process group viene
-  restituito un valore negativo il cui valore assoluto corrisponde
-  all'identificatore del process group.
+    (vedi \secref{sec:sess_proc_group}) raggruppamenti di processi usati nel
+    controllo di sessione; a ciascuno di essi è associato un identificatore
+    (un numero positivo analogo al \acr{pid}).}  che è preposto alla ricezione
+  dei segnali \const{SIGIO} e \const{SIGURG} per gli eventi associati al file
+  descriptor \param{fd}. Nel caso di un process group viene restituito un
+  valore negativo il cui valore assoluto corrisponde all'identificatore del
+  process group. In caso di errore viene restituito -1.
 \item[\const{F\_SETOWN}] imposta, con il valore dell'argomento \param{arg},
   l'identificatore del processo o del \textit{process group} che riceverà i
   segnali \const{SIGIO} e \const{SIGURG} per gli eventi associati al file
-  descriptor \param{fd}.  Come per \const{F\_GETOWN}, per impostare un process
-  group si deve usare per \param{arg} un valore negativo, il cui valore
-  assoluto corrisponde all'identificatore del process group.
+  descriptor \param{fd}, ritorna un valore nullo in caso di successo o -1 in
+  caso di errore.  Come per \const{F\_GETOWN}, per impostare un
+  \textit{process group} si deve usare per \param{arg} un valore negativo, il
+  cui valore assoluto corrisponde all'identificatore del \textit{process
+    group}.
 \item[\const{F\_GETSIG}] restituisce il valore del segnale inviato quando ci
   sono dati disponibili in ingresso su un file descriptor aperto ed impostato
   per l'I/O asincrono (si veda \secref{sec:file_asyncronous_io}). Il valore 0
   indica il valore predefinito (che è \const{SIGIO}), un valore diverso da
   zero indica il segnale richiesto, (che può essere anche lo stesso
-  \const{SIGIO}).
+  \const{SIGIO}). In caso di errore ritorna -1.
 \item[\const{F\_SETSIG}] imposta il segnale da inviare quando diventa
-  possibile effettuare I/O sul file descriptor in caso di I/O asincrono. Il
+  possibile effettuare I/O sul file descriptor in caso di I/O asincrono,
+  ritorna un valore nullo in caso di successo o -1 in caso di errore. Il
   valore zero indica di usare il segnale predefinito, \const{SIGIO}. Un altro
-  valore (compreso lo stesso \const{SIGIO}) specifica il segnale voluto; l'uso
-  di un valore diverso da zero permette inoltre, se si è installato il
-  gestore del segnale come \var{sa\_sigaction} usando
+  valore diverso da zero (compreso lo stesso \const{SIGIO}) specifica il
+  segnale voluto; l'uso di un valore diverso da zero permette inoltre, se si è
+  installato il gestore del segnale come \var{sa\_sigaction} usando
   \const{SA\_SIGINFO}, (vedi \secref{sec:sig_sigaction}), di rendere
-  disponibili al gestore informazioni ulteriori informazioni riguardo il
-  file che ha generato il segnale attraverso i valori restituiti in
-  \struct{siginfo\_t} (come vedremo in
-  \secref{sec:file_asyncronous_io}).\footnote{i due comandi \const{F\_SETSIG}
-    e \const{F\_GETSIG} sono una estensione specifica di Linux.}
+  disponibili al gestore informazioni ulteriori riguardo il file che ha
+  generato il segnale attraverso i valori restituiti in \struct{siginfo\_t}
+  (come vedremo in \secref{sec:file_asyncronous_io}).\footnote{i due comandi
+    \const{F\_SETSIG} e \const{F\_GETSIG} sono una estensione specifica di
+    Linux.}
+\item[\const{F\_SETLEASE}] imposta o rimuove un \textit{file
+    lease}\footnote{questa è una nuova funzionalità, specifica di Linux, e
+    presente solo a partire dai kernel della serie 2.4.x, in cui il processo
+    che detiene un \textit{lease} su un file riceve una notifica qualora un
+    altro processo cerca di eseguire una \func{open} o una \func{truncate} su
+    di esso.} sul file descriptor \var{fd} a seconda del valore del terzo
+  argomento, che in questo caso è un \ctyp{int}, ritorna un valore nullo in
+  caso di successo o -1 in caso di errore. Questa funzionalità avanzata è
+  trattata in dettaglio in \secref{sec:file_asyncronous_operation}.
+\item[\const{F\_GETLEASE}] restituisce il tipo di \textit{file lease} che il
+  processo detiene nei confronti del file descriptor \var{fd} o -1 in caso di
+  errore. Con questo comando il terzo argomento può essere omesso. Questa
+  funzionalità avanzata è trattata in dettaglio in
+  \secref{sec:file_asyncronous_operation}.
+\item[\const{F\_NOTIFY}] attiva un meccanismo di notifica per cui viene
+  riportata al processo chiamante, tramite il segnale \const{SIGIO} (o altro
+  segnale specificato con \const{F\_SETSIG}) ogni modifica eseguita o
+  direttamente sulla directory cui \var{fd} fa riferimento, o su uno dei file
+  in essa contenuti; ritorna un valore nullo in caso di successo o -1 in caso
+  di errore. Questa funzionalità avanzata, disponibile dai kernel della serie
+  2.4.x, è trattata in dettaglio in \secref{sec:file_asyncronous_operation}.
 \end{basedescript}
 
 La maggior parte delle funzionalità di \func{fcntl} sono troppo avanzate per
-poter essere affrontate in dettaglio a questo punto; saranno riprese più
-avanti quando affronteremo le problematiche ad esse relative (in particolare
-le tematiche relative all'I/O asincrono sono trattate in maniera esaustiva in
-\secref{sec:file_asyncronous_io} mentre quelle relative al \textit{file
+poter essere affrontate in tutti i loro aspetti a questo punto; saranno
+pertanto riprese più avanti quando affronteremo le problematiche ad esse
+relative. In particolare le tematiche relative all'I/O asincrono e ai vari
+meccanismi di notifica saranno trattate in maniera esaustiva in
+\secref{sec:file_asyncronous_operation} mentre quelle relative al \textit{file
   locking}\index{file!locking} saranno esaminate in
 \secref{sec:file_locking}).
 
+
 Si tenga presente infine che quando si usa la funzione per determinare le
 modalità di accesso con cui è stato aperto il file (attraverso l'uso del
 comando \const{F\_GETFL}) è necessario estrarre i bit corrispondenti nel