readdir()

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

Прототип:

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

Аргументы:

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

Библиотека:

libc

Описание:

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

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

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


Note: Результат использования потока каталога после вызова одной из функций семейства 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.


Note:
  • Возвращаемое значение 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 системной библиотеки