readdir()

Считать запись директории

Прототип:

#include <dirent.h>
                                       
struct dirent * readdir( DIR *dirp );

Аргументы:

dirp

Указатель на поток каталога для чтения.

Библиотека:

libc

Описание:

Функция readdir() считывает следующую запись о директории из директории dirp, являющейся возвращаемым значением функции opendir().

Возможен многократный вызов readdir() для получения списка всех сущностей, находящихся в директории opendir(). Вызов функции closedir() необходим для закрытия потока каталога и освобождения ресурсов, выделенных при вызове opendir().

Файл <dirent.h> определяет struct dirent и тип DIR, используемый в семействе функций readdir().

---

Результат использования потока каталога после вызова одной из функций семейства exec*() или spawn*() не определен. После вызова fork(), родитель или потомок (но не оба) могут продолжить обработку потока каталога, используя функции readdir() и rewinddir(). Если и родительский, и дочерний процессы используют эти функции, результат не определен. Любой (или оба) процесса могут использовать closedir().

---

Файл <dirent.h> также определяет следующие макросы для доступа к дополнительным данным, связанным с struct dirent:

_DEXTRA_FIRST( pdirent )

Получить указатель на первый блок данных, связанный со структурой pdirent.

_DEXTRA_NEXT( last)

Получить блок данных, следующий за блоком, на который указывает last.

_DEXTRA_VALID( extra, pdirent)

Равен 1, если extra является указателем на допустимый блок данных, связанный со структурой, на которую указывает pdirent.

Блоки данных описываются структурами dirent_extra или dirent_extra_stat :

struct dirent_extra {
    uint16_t            d_datalen;      /* data size (without header) */
    uint16_t            d_type;
    uint32_t            d_reserved;
    /* unsigned char    d_data[d_datalen] */
};
                                       
struct dirent_extra_stat {
    uint16_t            d_datalen;      /* sizeof(struct stat) */
    uint16_t            d_type;
    uint32_t            d_reserved;
    struct stat         d_stat;
};

Возможно использование этих макросов для просмотра данных, связанных с struct dirent:

for ( extra = _DEXTRA_FIRST( dirent ); _DEXTRA_VALID( extra, dirent ); extra = _DEXTRA_NEXT( extra ) )
{
    switch ( extra->d_type )
    {
        /* No data */
        case _DTYPE_NONE: 
            break;
        /* Data includes information as returned by stat() */
        case _DTYPE_STAT:
            break;
        /* Data includes information as returned by lstat() */
        case _DTYPE_LSTAT: 
            break;
        ...
    }
}

Если значением поля d_type является _DTYPE_STAT или _DTYPE_LSTAT, поле d_stat member указывает на struct stat (см. stat() по этой ссылке). Возможно использование функции dircntl() для запроса к файловой системе на включение этой дополнительной информации.

Возвращаемое значение:

В случае успешного завершения, функция возвращает указатель на объект struct dirent.

Если возникла ошибка или достигнут конец потока функция возвращает NULL, код ошибки записывается в errno.

---

Возвращаемое значение NULL неоднозначно; если вам нужно определить, указывает ли оно на ошибку (в отличие от конца потока каталога), установите для errno значение EOK перед каждым вызовом этой функции. Несмотря на то, что struct dirent объявлена однобайтовым полем d_name, под структуру, возвращаемую readdir() выделяется достаточно места для хранения имени целиком. Последующие вызовы readdir() с тем же потоком каталога могут перезаписать память, на которую указывает возвращаемый указатель.

---

Коды ошибок:

EBADF

Аргумент dirp не указывает на поток открытого каталога.

EOVERFLOW

Одно из значений в возвращаемой структуре не может быть правильно представлено.

Примеры:

Получить список файлов, содержащихся в каталоге /home/fred:

#include <stdio.h>
#include <dirent.h>
#include <stdlib.h>
                                       
int main( void )
{
    DIR             *dirp;
    struct dirent   *direntp;
                                       
    dirp = opendir( "/home/fred" );
    if ( dirp != NULL )
    {
        for ( ; ; )
        {
            direntp = readdir( dirp );
            if ( direntp == NULL )
                break;
                                       
            printf( "%s\n", direntp->d_name );
        }
                                       
        closedir( dirp );
            
        return (EXIT_SUCCESS);
    }
                                       
    return (EXIT_FAILURE);
}

Классификация:

POSIX 1003.1

Безопасность использования

Точка остановки потока

Да

Обработчик прерываний

Нет

Обработчик сигналов

Нет

В потоке

Нет

Тематические ссылки:

struct stat, closedir(), dircntl(), struct dirent, errno, lstat(), opendir(), readdir_r(), rewinddir(), seekdir(), telldir(), stat()

Предыдущий раздел: Описание API системной библиотеки