readdir(3)

NUME
readdir - citește un director

BIBLIOTECA
Biblioteca C standard (libc, -lc)

SINOPSIS
#include <dirent.h>

struct dirent *readdir(DIR *dirp);

DESCRIERE
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:

.d_ino
    Acesta este numărul nodului-i al fișierului din sistemul de fișiere care conține directorul în care a fost apelată funcția readdir(). Dacă intrarea de director este un punct de montare, atunci .d_ino diferă de .st_ino returnat de stat(2) pentru acest fișier: .d_ino este numărul nodului-i al punctului de montare, în timp ce .st_ino este numărul nodului-i al directorului rădăcină al sistemului de fișiere montat.

.d_off
    Valoarea returnată în .d_off este aceeași care ar fi returnată prin apelarea telldir(3) la poziția curentă în fluxul de directoare. Rețineți că, în ciuda tipului și numelui său, câmpul .d_off este rareori un fel de decalaj de director pe sistemele de fișiere moderne. Aplicațiile trebuie să trateze acest câmp ca pe o valoare opacă, fără a face presupuneri cu privire la conținutul său; consultați și telldir(3).

.d_reclen
    Aceasta este dimensiunea (în octeți) a înregistrării returnate. Aceasta poate să nu coincidă cu dimensiunea definiției structurii prezentate mai sus; a se vedea secțiunea VERSIUNI.

.d_type
    Acest câmp conține o valoare care indică tipul de fișier, ceea ce permite evitarea apelării lstat(2) dacă acțiunile ulterioare depind de tipul fișierului.

    Atunci când este definit un macro test de caracteristică adecvat (_DEFAULT_SOURCE de la glibc 2.19 sau _BSD_SOURCE la glibc 2.19 și versiunile anterioare), glibc definește următoarele constante macro pentru valoarea returnată în .d_type:

    DT_BLK
        Acesta este un dispozitiv de blocuri.

    DT_CHR
        Acesta este un dispozitiv de caractere.

    DT_DIR
        Acesta este un director.

    DT_FIFO
        Aceasta este o conductă cu nume (FIFO).

    DT_LNK
        Aceasta este o legătură simbolică.

    DT_REG
        Acesta este un fișier obișnuit.

    DT_SOCK
        Acesta este un soclu de domeniu UNIX.

    DT_UNKNOWN
        Tipul fișierului nu a putut fi determinat.

    În prezent, numai unele sisteme de fișiere (printre care: Btrfs, ext2, ext3 și ext4) au suport complet pentru returnarea tipului de fișier în .d_type. Toate aplicațiile trebuie să gestioneze în mod corespunzător o returnare de tip DT_UNKNOWN.

.d_name
    Acest câmp conține numele de fișier cu terminație nulă; a se vedea secțiunea VERSIUNI.

Datele returnate de readdir() pot fi suprascrise de apeluri ulterioare la readdir() pentru același flux de directoare.

VALOAREA RETURNATĂ
Î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.

ERORI-IEȘIRE

EBADF
    Descriptor de flux de director nevalid dirp.

ATRIBUTE
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.

VERSIUNI
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.

  Câmpul .d_name
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.

STANDARDE
POSIX.1-2008.

ISTORIC
POSIX.1-2001, SVr4, 4.3BSD.

NOTE
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.

CONSULTAȚI ȘI
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)

TRADUCERE
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 (https://www.gnu.org/licenses/gpl-3.0.html) 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.