Aggiunte readdir_r, telldir, seekdir e varie spiegazioni e macro relative la

manipolazione delle strutture dirent e relativi campi

diff --git a/filedir.tex b/filedir.tex
index bb7f8a61f01ce2feafd04caee2376776a33da67c..61e39aa08bc0961da309d618c5f3d8cc5d4f709c 100644 (file)
--- a/filedir.tex
+++ b/filedir.tex
@@ -720,7 +720,7 @@ solito si utilizza questa funzione in abbinamento alla funzione \func{fchdir}
 per cambiare la directory di lavoro (vedi \secref{sec:file_work_dir}) a quella
 relativa allo stream che si sta esaminando.
 
 per cambiare la directory di lavoro (vedi \secref{sec:file_work_dir}) a quella
 relativa allo stream che si sta esaminando.
 

-La lettura di una voce nella directory viene effettuata attraverso la funzione
+La lettura di una voce della directory viene effettuata attraverso la funzione

 \funcd{readdir}; il suo prototipo è:
 \begin{functions}
   \headdecl{sys/types.h} \headdecl{dirent.h} 
 \funcd{readdir}; il suo prototipo è:
 \begin{functions}
   \headdecl{sys/types.h} \headdecl{dirent.h} 


@@ -738,21 +738,55 @@ La lettura di una voce nella directory viene effettuata attraverso la funzione
 
 La funzione legge la voce corrente nella directory, posizionandosi sulla voce
 successiva.  I dati vengono memorizzati in una struttura \struct{dirent} (la
 
 La funzione legge la voce corrente nella directory, posizionandosi sulla voce
 successiva.  I dati vengono memorizzati in una struttura \struct{dirent} (la

-cui definizione in Linux è riportata in \figref{fig:file_dirent_struct}). La
-funzione restituisce il puntatore alla struttura; si tenga presente però che
-quest'ultima viene sovrascritta tutte le volte che si ripete una lettura sullo
-stesso stream.
+cui definizione\footnote{la definizione è quella usata a Linux, che si trova
+  nel file \file{/usr/include/bits/dirent.h}, essa non contempla la presenza
+  del campo \var{d\_namlen} che indica la lunghezza del nome del file (ed
+  infatti la macro \macro{\_DIRENT\_HAVE\_D\_NAMLEN} non è definita.}  è
+riportata in \figref{fig:file_dirent_struct}). La funzione restituisce il
+puntatore alla struttura; si tenga presente però che quest'ultima è allocata
+staticamente, per cui viene sovrascritta tutte le volte che si ripete una
+lettura sullo stesso stream.
+
+Di questa funzione esiste anche una versione rientrante, \func{readdir\_r} che
+non usa una struttura allocata staticamente, e può essere utilizzata anche con
+i thread; il suo prototipo è:
+\begin{functions}
+  \headdecl{sys/types.h} \headdecl{dirent.h} 
+  
+  \funcdecl{int readdir\_r(DIR *dir, struct dirent *entry,
+          struct dirent **result)}
+  
+  Legge una voce dal \textit{directory stream}.
+  
+  \bodydesc{La funzione restituisce 0 in caso di successo e -1 in caso di
+    errore, gli errori sono gli stessi di \func{readdir}.}
+\end{functions}
+
+La funzione restituisce in \param{result} (come \textit{value result
+  argument}) l'indirizzo dove sono stati salvati i dati, che di norma
+corriponde a quallo specificato dall'argomento \param{entry} (anche se non è
+assicurato che la funzione usi lo spazio fornito dall'utente).
+
+I vari campi di \struct{dirent} contengono le informazioni relative alle voci
+presenti nella directory; i soli campi sempre presenti secondo lo standard
+POSIX sono \var{d\_name}, che contiene il nome del file nella forma di una
+stringa terminata da uno zero,\footnote{lo standard POSIX non specifica una
+  lunghezza, ma solo un limite \const{NAME\_MAX}, anche se di norma il valore
+  massimo per un nome è di 256 byte.} e \var{d\_fileno} che contiene il numero
+di inode cui il file è associato (di solito corriponde al campo \var{st\_ino}
+di \struct{stat}); questo campo viene anche chiamato \var{d\_ino}, per
+compatibilità con la definizione usata da BSD.

 
 \begin{figure}[!htb]
   \footnotesize \centering
   \begin{minipage}[c]{15cm}
     \begin{lstlisting}[labelstep=0]{}%,frame=,indent=1cm]{}
 struct dirent {
 
 \begin{figure}[!htb]
   \footnotesize \centering
   \begin{minipage}[c]{15cm}
     \begin{lstlisting}[labelstep=0]{}%,frame=,indent=1cm]{}
 struct dirent {

-    ino_t d_ino;                  /* inode number */
-    off_t d_off;                  /* offset to the next dirent */
-    unsigned short int d_reclen;  /* length of this record */
-    unsigned char d_type;         /* type of file */
-    char d_name[256];             /* We must not include limits.h! */
+    ino_t d_fileno;                 /* inode number */
+    off_t d_off;                    /* offset to the next dirent */
+    unsigned short int d_reclen;    /* length of this record */
+    unsigned char d_type;           /* type of file */
+    char d_name[256];               /* We must not include limits.h! */

 };
     \end{lstlisting}
   \end{minipage} 
 };
     \end{lstlisting}
   \end{minipage} 


@@ -762,19 +796,11 @@ struct dirent {
   \label{fig:file_dirent_struct}
 \end{figure}
 
   \label{fig:file_dirent_struct}
 \end{figure}
 

-I vari campi contengono le informazioni relative ai file della directory; il
-solo campo obbligatorio secondo lo standard POSIX è \var{d\_name}, che
-contiene il nome del file nella forma di una stringa terminata da uno zero, la
-cui lunghezza è riportata nel campo \var{d\_reclen}.\footnote{lo standard
-  POSIX non specifica una lunghezza, ma solo un limite \const{NAME\_MAX},
-  anche se di norma il valore massimo per un nome è di 256 byte.}
-
-Il campo \var{d\_ino} contiene il numero di inode cui il file è associato ed
-il campo \var{d\_type} il tipo di file (fifo, directory, link simbolico,
-ecc.). Entrambi questi campi derivano da BSD e non appartengono allo standard;
-la presenza del tipo di file è segnalata dalla macro
-\macro{\_DIRENT\_HAVE\_D\_TYPE}; i possibili valori del campo \var{d\_type}
-sono riportati in \tabref{tab:file_dtype_macro}.
+La presenza di ulteriori campi opzionali è segnalata dalla definizione di
+altrettante macro nella forma \code{\_DIRENT\_HAVE\_D\_XXX} dove \code{XXX} è
+il nome del relativo campo; nel nostro caso sono definite le macro
+\macro{\_DIRENT\_HAVE\_D\_TYPE}, \macro{\_DIRENT\_HAVE\_D\_OFF} e
+\macro{\_DIRENT\_HAVE\_D\_RECLEN}.

 
 \begin{table}[htb]
   \centering
 
 \begin{table}[htb]
   \centering


@@ -798,6 +824,43 @@ sono riportati in \tabref{tab:file_dtype_macro}.
   \label{tab:file_dtype_macro}
 \end{table}
 
   \label{tab:file_dtype_macro}
 \end{table}
 

+Il campo \var{d\_type} indica il tipo di file (fifo, directory, link
+simbolico, ecc.); i suoi possibili valori sono riportati in
+\tabref{tab:file_dtype_macro}; per la conversione da e verso l'analogo valore
+mantenuto dentro il campo \var{st\_mode} di \struct{stat} sono definite anche
+due macro di conversione \macro{IFTODT} e \macro{DTTOIF}:
+\begin{functions}
+  \funcdecl{int IFTODT(mode\_t MODE)} Converte il tipo di file dal formato di
+  \var{st\_mode} a quello di \var{d\_type}.
+  
+  \funcdecl{mode\_t DTTOIF(int DTYPE)} Converte il tipo di file dal formato di
+  \var{d\_type} a quello di \var{st\_mode}.
+\end{functions}
+
+Il campo \var{d\_off} contiene la posizione della successiva voce nella
+directory, mentre il campo \var{d\_reclen} la lunghezza totale della voce. Con
+questi campi diventa possibile spostarsi all'interno dello stream usando la
+funzione \func{seekdir},\footnote{sia questa funzione, che la corrispondente
+  \func{telldir}, sono estensioni prese da BSD, non previste dallo standard
+  POSIX.} il cui prototipo è:
+\begin{prototype}{dirent.h}{void seekdir(DIR *dir, off\_t offset)}
+  Cambia la posizione all'interno di un \textit{directory stream}.
+\end{prototype}
+
+La funzione non ritorna nulla e non segnala errori, è però necessario che il
+valore dell'argomento \param{offset} sia valido per lo stream \param{dir};
+esso pertanto deve essere stato ottenuto o dal valore di \var{d\_off} di
+\struct{dirent} o dal valore restituito dalla funzione \func{telldir}, che
+legge la posizione corrente; il prototipo di quest'ultima è:
+\begin{prototype}{dirent.h}{off\_t telldir(DIR *dir)}
+  Ritorna la posizione corrente in un \textit{directory stream}.
+  
+  \bodydesc{La funzione restituisce la posizione corrente nello stream (un
+    numero positivo) in caso di successo, e -1 altrimenti, nel qual caso
+    \var{errno} assume solo il valore di \errval{EBADF}, corrispondente ad un
+    valore errrato per \param{dir}.}
+\end{prototype}
+