From: Simone Piccardi Date: Sat, 28 Dec 2002 14:37:30 +0000 (+0000) Subject: Aggiunte readdir_r, telldir, seekdir e varie spiegazioni e macro relative la X-Git-Url: https://gapil.gnulinux.it/gitweb/?p=gapil.git;a=commitdiff_plain;h=1a416451168660c50fefa8802e5d531e331c8063 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 bb7f8a6..61e39aa 100644 --- 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. -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} @@ -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 -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 { - 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} @@ -762,19 +796,11 @@ struct dirent { \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 @@ -798,6 +824,43 @@ sono riportati in \tabref{tab:file_dtype_macro}. \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} +