| readdir(3) | Library Functions Manual | readdir(3) |
readdir - citește un director
Biblioteca C standard (libc, -lc)
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
Funcția readdir() returnează un indicator către o structură dirent care reprezintă următoarea intrare de director din fluxul de directoare indicat de dirp. Aceasta returnează NULL dacă se ajunge la sfârșitul fluxului de directoare sau dacă s-a produs o eroare.
În implementarea glibc, structura dirent este definită după cum urmează:
struct dirent {
ino_t d_ino; /* Numărul nodului-i */
off_t d_off; /* Nu este un decalaj; a se vedea mai jos */
unsigned short d_reclen; /* Lungimea acestei înregistrări */
unsigned char d_type; /* Tipul de fișier; nu este acceptat
de către toate tipurile de sisteme de fișiere */
char d_name[256]; /* Nume de fișier cu terminație nulă */
};
Singurele câmpuri din structura dirent care sunt impuse de POSIX.1 sunt d_name și d_ino. Celelalte câmpuri nu sunt standardizate și nu sunt prezente pe toate sistemele; a se vedea secțiunea VERSIUNI.
Câmpurile structurii dirent sunt următoarele:
Datele returnate de readdir() pot fi suprascrise de apeluri ulterioare la readdir() pentru același flux de directoare.
În caz de succes, readdir() returnează un indicator către o structură dirent. Această structură poate fi alocată static; nu încercați să o eliberați cu free(3).
Dacă se ajunge la sfârșitul fluxului de directoare, se returnează NULL și errno nu este modificată. Dacă apare o eroare, NULL este returnat și errno este configurată pentru a indica eroarea. Pentru a distinge sfârșitul fluxului de o eroare, definiți errno la zero înainte de a apela readdir() și apoi verificați valoarea lui errno dacă este returnat NULL.
Pentru o explicație a termenilor folosiți în această secțiune, a se vedea attributes(7).
| Interfață | Atribut | Valoare |
| readdir() | Siguranța firelor | MT-Unsafe race:dirstream |
În actuala specificație POSIX.1 (POSIX.1-2008), readdir() nu este necesar să fie sigur pentru fir. Cu toate acestea, în implementările moderne (inclusiv implementarea glibc), apelurile concurente la readdir() care specifică fluxuri de directoare diferite sunt sigure pentru fire. În cazurile în care mai multe fire de execuție trebuie să citească din același flux de directoare, utilizarea readdir() cu sincronizare externă este preferabilă utilizării funcției depreciate readdir_r(3). Se preconizează că o versiune viitoare a POSIX.1 va solicita ca funcția readdir() să fie sigură pentru fire atunci când este utilizată concomitent pe diferite fluxuri de directoare.
Doar câmpurile d_name și (ca extensie XSI) d_ino sunt specificate în POSIX.1. În afară de Linux, câmpul d_type este disponibil în principal numai pe sistemele BSD. Celelalte câmpuri sunt disponibile pe multe, dar nu pe toate sistemele. Sub glibc, programele pot verifica disponibilitatea câmpurilor care nu sunt definite în POSIX.1 testând dacă macro-urile _DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF sau _DIRENT_HAVE_D_TYPE sunt definite.
Definiția structurii dirent prezentată mai sus este preluată din anteturile glibc și prezintă câmpul d_name cu o dimensiune fixă.
Avertisment: aplicațiile trebuie să evite orice dependență de dimensiunea câmpului d_name. POSIX îl definește ca fiind char d_name[], o matrice de caractere de dimensiune nespecificată, cu cel mult NAME_MAX caractere care preced octetul nul final („\0”).
POSIX.1 menționează în mod explicit că acest câmp nu ar trebui să fie utilizat ca o valoare „lvalue”. Standardul menționează, de asemenea, că utilizarea sizeof(d_name) este incorectă; utilizați în schimb strlen(d_name); (pe unele sisteme, acest câmp este definit ca char d_name[1]!) Implicit, utilizarea sizeof(struct dirent) pentru a capta dimensiunea înregistrării, inclusiv dimensiunea lui d_name, este de asemenea incorectă.
Rețineți că, în timp ce apelul
fpathconf(fd, _PC_NAME_MAX)
returnează valoarea 255 pentru majoritatea sistemelor de fișiere, pe unele sisteme de fișiere (de exemplu, CIFS, servere Windows SMB), numele de fișier cu terminație nulă care este (corect) returnat în d_name poate depăși de fapt această dimensiune. În astfel de cazuri, câmpul d_reclen va conține o valoare care depășește dimensiunea structurii glibc dirent prezentată mai sus.
POSIX.1-2008.
POSIX.1-2001, SVr4, 4.3BSD.
Un flux de directoare este deschis utilizând opendir(3).
Ordinea în care numele de fișiere sunt citite prin apeluri succesive la readdir() depinde de implementarea sistemului de fișiere; este puțin probabil ca numele să fie sortate în vreun fel.
getdents(2), read(2), closedir(3), dirfd(3), ftw(3), offsetof(3), opendir(3), readdir_r(3), rewinddir(3), scandir(3), seekdir(3), telldir(3)
Traducerea în limba română a acestui manual a fost făcută de Remus-Gabriel Chelu <remusgabriel.chelu@disroot.org>
Această traducere este documentație gratuită; citiți Licența publică generală GNU Versiunea 3 sau o versiune ulterioară cu privire la condiții privind drepturile de autor. NU se asumă NICIO RESPONSABILITATE.
Dacă găsiți erori în traducerea acestui manual, vă rugăm să trimiteți un e-mail la translation-team-ro@lists.sourceforge.net.
| 16 iunie 2024 | Pagini de manual de Linux 6.9.1 |