Ancora at-functions
authorSimone Piccardi <piccardi@gnulinux.it>
Sat, 26 Jan 2019 23:41:57 +0000 (00:41 +0100)
committerSimone Piccardi <piccardi@gnulinux.it>
Sat, 26 Jan 2019 23:41:57 +0000 (00:41 +0100)
fileio.tex

index bc3edfb..7c2a171 100644 (file)
@@ -739,13 +739,13 @@ torni a corrispondere al valore di \const{O\_DSYNC}.
 % NOTE: per le differenze fra O_DSYNC, O_SYNC e O_RSYNC introdotte nella  
 % nello sviluppo del kernel 2.6.33, vedi http://lwn.net/Articles/350219/ 
 
-Il flag \constd{O\_PATH}, introdotto con il kernel 2.6.39, viene usato per
-limitare l'uso del file descriptor restituito da \func{open} o
-all'identificazione di una posizione sul filesystem (ad uso delle
-\textit{at-functions} che tratteremo in sez.~\ref{sec:file_openat}) o alle
-operazioni che riguardano il file descriptor in quanto tale, senza consentire
-operazioni sul file; in sostanza se si apre un file con \const{O\_PATH} si
-potrà soltanto:
+Il flag \constd{O\_PATH},\label{open_o_path_flag} introdotto con il kernel
+2.6.39, viene usato per limitare l'uso del file descriptor restituito da
+\func{open} o all'identificazione di una posizione sul filesystem (ad uso
+delle \textit{at-functions} che tratteremo in sez.~\ref{sec:file_openat}) o
+alle operazioni che riguardano il file descriptor in quanto tale, senza
+consentire operazioni sul file; in sostanza se si apre un file con
+\const{O\_PATH} si potrà soltanto:
 \begin{itemize*}
 \item usare il file descriptor come indicatore della directory di partenza con
   una delle \textit{at-functions} (vedi sez.~\ref{sec:file_openat});
@@ -1848,9 +1848,9 @@ riferimento ad una directory, tranne il caso in cui si sia specificato un
     \hline
      \func{execveat}  &$\bullet$&\func{execve}  \\
      \func{faccessat} &$\bullet$&\func{access}  \\
-     \funcm{fchmodat} &$\bullet$&\func{chmod}   \\
+     \func{fchmodat}  &$\bullet$&\func{chmod}   \\
      \func{fchownat}  &$\bullet$&\func{chown},\func{lchown}\\
-     \funcm{fstatat}  &$\bullet$&\func{stat},\func{lstat}  \\
+     \func{fstatat}   &$\bullet$&\func{stat},\func{lstat}  \\
      \funcm{futimesat}& --      & obsoleta  \\
      \func{linkat}    &$\bullet$&\func{link}    \\
      \funcm{mkdirat}  & --      &\func{mkdir}   \\
@@ -1858,10 +1858,10 @@ riferimento ad una directory, tranne il caso in cui si sia specificato un
      \funcm{mknodat}  & --      &\func{mknod}   \\
      \func{openat}    & --      &\func{open}    \\
      \funcm{readlinkat}& --     &\func{readlink}\\
-     \funcm{renameat} & --      &\func{rename}  \\
-     \funcm{renameat2}\footnotemark& -- &\func{rename}  \\
+     \func{renameat}  & --      &\func{rename}  \\
+     \func{renameat2}\footnotemark& -- &\func{rename}  \\
      \funcm{scandirat}& --      &\func{scandir}  \\
-     \funcm{statx}    &$\bullet$&\func{stat}  \\
+     \func{statx}     &$\bullet$&\func{stat}  \\
      \funcm{symlinkat}& --      &\func{symlink} \\
      \func{unlinkat}  &$\bullet$&\func{unlink},\func{rmdir}  \\
      \func{utimensat} &$\bullet$&\func{utimes},\func{lutimes}\\
@@ -1885,40 +1885,91 @@ tab.~\ref{tab:file_atfunc_corr}, oltre al nuovo argomento iniziale, è prevista
 anche l'aggiunta di un argomento finale, \param{flags}, che è stato introdotto
 per fornire un meccanismo con cui modificarne il comportamento.
 
-Buona parte di queste funzioni hanno un comportamento identico alla
-corrispondente funzione ordinaria, pertanto non le tratteremo esplicitamente,
-vale per loro quanto detto con \func{openat} per l'uso del nuovo argomento
-\param{dirfd}. 
+Per tutte quelle che non hanno un argomento aggiuntivo il comportamento è
+identico alla corrispondente funzione ordinaria, pertanto non le tratteremo
+esplicitamente, vale per loro quanto detto con \func{openat} per l'uso del
+nuovo argomento \param{dirfd}. Quando invece l'argomento è presente il
+comportamento viene modificato a seconda del valore assegnato a \param{flags},
+che deve essere passato come maschera binaria con una opportuna combinazione
+delle costanti elencate in tab.~\ref{tab:at-functions_constant_values}, in
+quanto sono possibili diversi valori a seconda della funzione usata.
 
+\begin{table}[htb]
+  \centering
+  \footnotesize
+  \begin{tabular}[c]{|l|p{8cm}|}
+    \hline
+    \textbf{Costante} & \textbf{Significato} \\
+    \hline
+    \hline
+    \constd{AT\_EMPTY\_PATH}    & Usato per operare direttamente (specificando
+                                  una stringa vuota  per il \texttt{pathname})
+                                  sul file descriptor \param{dirfd} che in
+                                  questo caso può essere un file qualunque.\\
+    \constd{AT\_SYMLINK\_NOFOLLOW}& Se impostato la funzione non esegue la
+                                    dereferenziazione dei collegamenti
+                                    simbolici.\\
+    \hline
+    \constd{AT\_EACCES}         & Usato solo da \func{faccessat}, richiede che
+                                  il controllo dei permessi sia fatto usando
+                                  l'\ids{UID} effettivo invece di quello
+                                  reale.\\
+    \constd{AT\_NO\_AUTOMOUNT}  & Usato solo da \func{fstatat} e \func{statx},
+                                  evita il montaggio automatico qualora 
+                                  \param{pathname} faccia riferimento ad una
+                                  directory marcata per
+                                  l'\textit{automount}\footnotemark
+                                  (dal kernel 2.6.38).\\
+    \constd{AT\_REMOVEDIR}      & Usato solo da \func{unlinkat}, richiede che
+                                  la funzione si comporti come \func{rmdir}
+                                  invece che come \func{unlink}.\\
+    \constd{AT\_SYMLINK\_FOLLOW}& Usato solo da \func{linkat}, se impostato la
+                                  funzione esegue la dereferenziazione dei
+                                  collegamenti simbolici.\\
+    \hline
+  \end{tabular}  
+  \caption{Le costanti utilizzate per i bit dell'argomento aggiuntivo
+    \param{flags} delle \textit{at-functions}, definite in
+    \headfile{fcntl.h}.}
+  \label{tab:at-functions_constant_values}
+\end{table}
 
-
-Il solo caso generale, valido per tutte, è quello in cui si sta operando su un
-collegamento simbolico, e si vuole poter scegliere se far agire la funzione
-direttamente sullo stesso o sul file da esso referenziato. Ma oltre a questo
-caso generico, l'argomento viene usato per controllare ulteriori
-caratteristiche di funzionamento, dipendenti dalla funzione stessa; per questo
-motivo deve essere comunque passato come maschera binaria ed impostato usando
-i valori delle appropriate costanti \texttt{AT\_*}, definite in
-\headfile{fcntl.h}.
-
-%% Verificare uso generico di AT_EMPTY_XX
-
-% TODO: trattare i nuovi AT_flags quando e se arriveranno, vedi
-% https://lwn.net/Articles/767547/ 
-
-Per tutte le funzioni che lo prevedono, a parte \func{unlinkat} e
-\funcd{faccessat}, l'ulteriore argomento è stato introdotto solo per fornire
-un meccanismo con cui modificarne il comportamento nel caso si stia operando
-su un collegamento simbolico, così da poter scegliere se far agire la funzione
-direttamente sullo stesso o sul file da esso referenziato. Dato che in certi
-casi esso può fornire ulteriori indicazioni per modificare il comportamento
-delle funzioni, \param{flags} deve comunque essere passato come maschera
-binaria, ed impostato usando i valori delle appropriate costanti
-\texttt{AT\_*}, definite in \headfile{fcntl.h}.
-
-Come esempio di questo secondo tipo di funzioni possiamo considerare
-\funcd{fchownat}, che può essere usata per sostituire sia \func{chown}
-che \func{lchown}; il suo prototipo è:
+\footnotetext{si tratta di una funzionalità fornita dal kernel che consente di
+  montare automaticamente una directory quando si accede ad un
+  \textit{pathname} al di sotto di essa, per i dettagli, più di natura
+  sistemistica, si può consultare sez.~5.1.6 di \cite{AGL}.}
+
+Si tenga presente che non tutte le funzioni che prevedono l'argomento
+aggiuntivo sono \textit{system call}, ad esempio \func{faccessat} e
+\func{fchmodat} sono realizzate con dei \textit{wrapper} nella \acr{glibc} per
+aderenza allo standard POSIX.1-2008, dato che la \textit{system call}
+sottostante non prevede l'argomento \param{flags}. 
+
+In tab.~\ref{tab:at-functions_constant_values} si sono elencati i valori
+utilizzabili per i flag (tranne quelli specifici di \func{statx} su cui
+torneremo più avanti), mantenendo nella prima parte quelli comuni usati da più
+funzioni. Il primo di questi è \const{AT\_SYMLINK\_NOFOLLOW}, che viene usato
+da tutte le funzioni tranne \func{linkat} e \func{unlinkat}, e che consente di
+scegliere, quando si sta operando su un collegamento simbolico, se far agire
+la funzione direttamente sullo stesso o sul file da esso referenziato. Si
+tenga presente però che per \func{fchmodat} questo, che è l'unico flag
+consentito e previsto dallo standard, non è attualmente implementato (anche
+perché non avrebbe molto senso cambiare i permessi di un link simbolico) e
+pertanto l'uso della funzione è analogo a quello delle altre funzioni che non
+hanno l'argomento \param{flags}.
+
+L'altro flag comune è \const{AT\_EMPTY\_PATH}, utilizzabile a partire dal
+kernel 2.6.39, che consente di usare per \param{dirfd} un file descriptor
+associato ad un file qualunque e non necessariamente ad una directory; in
+particolare si può usare un file descriptor ottenuto aprendo un file con il
+flag \param{O\_PATH} (vedi quanto illustrato a
+pag.~\pageref{open_o_path_flag}). Quando si usa questo flag \param{pathname}
+deve essere vuoto, da cui il nome della costante, ed in tal caso la funzione
+agirà direttamente sul file associato al file descriptor \param{dirfd}.
+
+Come esempio di funzione che utilizza solo questi due flag generici possiamo
+considerare \funcd{fchownat}, che può essere usata per sostituire sia
+\func{chown} che \func{lchown}; il suo prototipo è:
 
 \begin{funcproto}{
 \fhead{unistd.h}
@@ -1939,17 +1990,14 @@ che \func{lchown}; il suo prototipo è:
 }  
 \end{funcproto}
 
-In questo caso il valore di \param{flags} stabilisce il comportamento della
-funzione quando la si applica ad un collegamento simbolico, e l'unico valore
-utilizzabile è \const{AT\_SYMLINK\_NOFOLLOW}, che se impostato indica alla
+In questo caso se si è impostato \const{AT\_SYMLINK\_NOFOLLOW} si indica alla
 funzione di non eseguire la dereferenziazione di un eventuale collegamento
 simbolico, facendo comportare \func{fchownat} come \func{lchown} invece che
-come \func{chown}.
+come \func{chown}. 
 
-Come accennato fra tutte quelle marcate in tab.~\ref{tab:file_atfunc_corr}
-solo due funzioni possono usare l'argomento \param{flags} per indicare altro
-rispetto alla possibilità di seguire o meno un collegamento simbolico, la
-prima di queste è \funcd{faccessat}, ed il suo prototipo è:
+Un'altra funzione che utilizza l'argomento \param{flags}, usandolo per
+indicare altro rispetto alla possibilità di seguire o meno un collegamento
+simbolico, è \funcd{faccessat}, ed il suo prototipo è:
 
 \begin{funcproto}{
 \fhead{unistd.h}
@@ -1968,20 +2016,19 @@ prima di queste è \funcd{faccessat}, ed il suo prototipo è:
 }  
 \end{funcproto}
 
-La funzione esegue il controllo di accesso ad un file, ma
-l'argomento \param{flags} consente di modificarne il comportamento rispetto a
-quello ordinario di \func{access}. In questo caso esso può essere specificato
-come maschera binaria di due valori: il solito \const{AT\_SYMLINK\_NOFOLLOW},
-con il significato già spiegato, e \const{AT\_EACCES} per indicare alla
-funzione di eseguire il controllo dei permessi usando l'\ids{UID} effettivo
-invece di quello reale (il comportamento di default, che riprende quello di
-\func{access}).
-
+La funzione esegue il controllo di accesso ad un file, ma l'argomento
+\param{flags} consente di modificarne il comportamento rispetto a quello
+ordinario di \func{access}. In questo caso esso può essere specificato come
+maschera binaria di due valori: il solito \const{AT\_SYMLINK\_NOFOLLOW}, con
+il significato già spiegato, e \const{AT\_EACCES} per indicare alla funzione
+di eseguire il controllo dei permessi usando l'\ids{UID} effettivo invece di
+quello reale (il comportamento di default, che riprende quello di
+\func{access}). 
 
-La seconda eccezione è \funcd{unlinkat}, in questo caso
-l'argomento \param{flags} viene utilizzato perché tramite esso si può indicare
-alla funzione di comportarsi sia come analogo di \func{unlink} che di
-\func{rmdir}; il suo prototipo è:
+Un'altra funzione che ha un utilizzo specifico dell'argomento \param{flags} è
+\funcd{unlinkat}: in questo caso l'argomento viene utilizzato perché tramite
+esso si può indicare alla funzione di comportarsi sia come analogo di
+\func{unlink} che di \func{rmdir}; il suo prototipo è:
 
 \begin{funcproto}{
 \fhead{fcntl.h}
@@ -2004,26 +2051,48 @@ alla funzione di comportarsi sia come analogo di \func{unlink} che di
 Di default il comportamento di \func{unlinkat} è equivalente a quello che
 avrebbe \func{unlink} applicata a \param{pathname}, fallendo in tutti i casi
 in cui questo è una directory, se però si imposta \param{flags} al valore di
-\const{AT\_REMOVEDIR}, essa si comporterà come \func{rmdir}, in tal
-caso \param{pathname} deve essere una directory, che sarà rimossa qualora
-risulti vuota.  Non essendo in questo caso prevista la possibilità di usare
-altri valori (la funzione non segue comunque i collegamenti simbolici) anche
-se \param{flags} è una maschera binaria, essendo \const{AT\_REMOVEDIR} l'unico
-flag disponibile per questa funzione, lo si può assegnare direttamente.
-
-Infine una terza funzione, \funcm{linkat}, utilizza in maniera diversa dalle
-altre l'argomento \param{flags},\footnote{si tenga presente che per questa
-  funzione l'argomento \param{flags} è disponibile ed utilizzabile solo a
-  partire dal kernel 2.6.18.} anche se in questo caso l'utilizzo continua ad
-essere attinente al comportamento con i collegamenti simbolici. Si ricordi che
-su Linux il comportamento di \func{link} è quello di non seguire mai i
-collegamenti simbolici, pertanto l'uso ordinario dell'argomento parrebbe in
-questo caso essere inutile.  A partire dal kernel 2.6.18 invece però è stato
-aggiunta per questa funzione la possibilità di usare il valore
-\const{AT\_SYMLINK\_FOLLOW}, che richiede di dereferenziare i collegamenti
-simbolici.
+\const{AT\_REMOVEDIR}, essa si comporterà come \func{rmdir}, in tal caso
+\param{pathname} deve essere una directory, che sarà rimossa qualora risulti
+vuota.  Non essendo in questo caso prevista la possibilità di usare altri
+valori (la funzione non segue comunque i collegamenti simbolici e
+\const{AT\_EMPTY\_PATH} non è supportato) anche se \param{flags} è una
+maschera binaria, essendo \const{AT\_REMOVEDIR} l'unico flag disponibile per
+questa funzione, lo si può assegnare direttamente.
+
+Ancora diverso è il caso di \funcd{linkat},\footnote{si tenga presente che per
+  questa funzione l'argomento \param{flags} è disponibile ed utilizzabile solo
+  a partire dal kernel 2.6.18.} anche se in questo caso l'utilizzo continua ad
+essere attinente al comportamento con i collegamenti simbolici, il suo
+prototipo è:
+
+\begin{funcproto}{
+\fhead{fcntl.h}
+\fdecl{int linkat(int olddirfd, const char *oldpath, int newdirfd, \\
+\phantom{int linkat(}const char *newpath, int flags)}
+\fdesc{Crea un nuovo collegamento diretto (\textit{hard link}).} 
+}
+
+{La funzione ritorna gli stessi valori e gli stessi codici di errore di
+  \func{link}, ed in più:
+  \begin{errlist}
+  \item[\errcode{EBADF}] \param{olddirfd} o \param{newdirfd} non sono un file
+    descriptor valido.
+  \item[\errcode{EINVAL}] \param{flags} non ha un valore valido.
+  \item[\errcode{ENOTDIR}] \param{oldpath} e \param{newpath} è un
+    \textit{pathname} relativo, ma \param{oldirfd} o \param{newdirfd} fa
+    riferimento ad un file.
+  \end{errlist}
+}  
+\end{funcproto}
 
+In questo caso 
 
+Si ricordi che su Linux il comportamento di \func{link} è quello di non
+seguire mai i collegamenti simbolici, pertanto l'uso ordinario dell'argomento
+parrebbe in questo caso essere inutile.  A partire dal kernel 2.6.18 invece
+però è stato aggiunta per questa funzione la possibilità di usare il valore
+\const{AT\_SYMLINK\_FOLLOW}, che richiede di dereferenziare i collegamenti
+simbolici.
 
 
 
@@ -2034,43 +2103,6 @@ usare \const{AT\_SYMLINK\_NOFOLLOW}. Per avere un quadro d'insieme si è
 riassunto in tab.~\ref{tab:at-functions_constant_values} l'elenco delle
 costanti utilizzabili per i valori di \param{flags}.
 
-\begin{table}[htb]
-  \centering
-  \footnotesize
-  \begin{tabular}[c]{|l|p{8cm}|}
-    \hline
-    \textbf{Costante} & \textbf{Significato} \\
-    \hline
-    \hline
-    \constd{AT\_EACCES}         & Usato solo da \func{faccessat}, richiede che
-                                  il controllo dei permessi sia fatto usando
-                                  l'\ids{UID} effettivo invece di quello
-                                  reale.\\
-    \constd{AT\_EMPTY\_PATH}    & Usato da varie funzioni per operare 
-                                  direttamente (specificando una stringa vuota
-                                  per il \texttt{pathname}) sul file descriptor
-                                  \param{dirfd} che in questo caso deve essere
-                                  ottenuto aprendo un file, che
-                                  può non essere una directory, con il flag
-                                  \param{O\_PATH} (vedi 
-                                  sez.~\ref{sec:file_open_close}).\\
-    \constd{AT\_REMOVEDIR}      & Usato solo da \func{unlinkat}, richiede che
-                                  la funzione si comporti come \func{rmdir}
-                                  invece che come \func{unlink}.\\
-    \constd{AT\_SYMLINK\_FOLLOW}& Se impostato la funzione esegue la
-                                  dereferenziazione dei collegamenti simbolici
-                                  (usato esplicitamente solo da
-                                  \func{linkat}).\\ 
-    \constd{AT\_SYMLINK\_NOFOLLOW}& Se impostato la funzione non esegue la
-                                    dereferenziazione dei collegamenti
-                                    simbolici.\\ 
-    \hline
-  \end{tabular}  
-  \caption{Le costanti utilizzate per i bit dell'argomento
-    aggiuntivo \param{flags} delle \textit{at-functions}.} 
-  \label{tab:at-functions_constant_values}
-\end{table}
-
 
 
 
@@ -2093,6 +2125,9 @@ costanti utilizzabili per i valori di \param{flags}.
 % https://lwn.net/Articles/626150/ cerca anche fexecve
 
 
+% TODO: trattare i nuovi AT_flags quando e se arriveranno, vedi
+% https://lwn.net/Articles/767547/ 
+
 \texttt{ATTENZIONE PARTE DA RIVEDERE}