Provided by: manpages-ru-dev_4.27.0-1_all 
НАИМЕНОВАНИЕ
readdir - чтение содержимого каталога
БИБЛИОТЕКА
Стандартная библиотека языка C (libc, -lc)
ОБЗОР
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
ОПИСАНИЕ
Функция readdir() возвращает указатель на структуру dirent, представляющую следующую запись каталога в
потоке каталога, указанного в dirp. Функция возвращает NULL по достижении последней записи в потоке
каталога или если произошла ошибка.
В реализации glibc структура dirent определена следующим образом:
struct dirent {
ino_t d_ino; /* номер иноды */
off_t d_off; /* не смещение, смотрите ниже */
unsigned short d_reclen; /* длина этой записи */
unsigned char d_type; /* тип файла; поддерживается
не во всех файловых системах */
char d_name[256]; /* имя файла с null в конце */
};
The only fields in the dirent structure that are mandated by POSIX.1 are d_name and d_ino. The other
fields are unstandardized, and not present on all systems; see VERSIONS.
Поля структуры dirent:
d_ino Номер иноды файла.
d_off Значение, возвращаемое в d_off, тоже самое что и после вызова telldir(3) в текущем положении
курсора в потоке каталога. Учтите, что не смотря на тип и имя, в современных файловых системах
поле d_off мало похоже на смещение в каталоге. Приложения должны считать, что это поле
неизвестного типа(чёрным ящиком) и не делать предположений о его содержимом; смотрите также
telldir(3).
d_reclen
This is the size (in bytes) of the returned record. This may not match the size of the structure
definition shown above; see VERSIONS.
d_type Это поле содержит значение типа файла, что позволяет не делать дополнительный вызов lstat(2), если
дальнейшие действия зависят от типа файла.
When a suitable feature test macro is defined (_DEFAULT_SOURCE since glibc 2.19, or _BSD_SOURCE on
glibc 2.19 and earlier), glibc defines the following macro constants for the value returned in
d_type:
DT_BLK блочное устройство
DT_CHR символьное устройство
DT_DIR каталог
DT_FIFO именованный канал (FIFO)
DT_LNK символическая ссылка
DT_REG обычный файл
DT_SOCK доменный сокет UNIX
DT_UNKNOWN Тип файла невозможно определить.
В настоящее время, только файловые системы (среди которых: Btrfs, ext2, ext3 и ext4) поддерживают
возврат типа файла в d_type. Все приложения должны правильно обрабатывать возвращаемое значение
DT_UNKNOWN.
d_name This field contains the null terminated filename; see VERSIONS.
Данные, возвращаемые readdir(), могут быть переписаны последующими вызовами readdir() для того же потока
каталога.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении readdir() возвращает указатель на структуру dirent (эта структура может
выделяться статически; не пытайтесь освободить её с помощью free(3)).
If the end of the directory stream is reached, NULL is returned and errno is not changed. If an error
occurs, NULL is returned and errno is set to indicate the error. To distinguish end of stream from an
error, set errno to zero before calling readdir() and then check the value of errno if NULL is returned.
ОШИБКИ
EBADF Неверный дескриптор потока каталога dirp.
АТРИБУТЫ
Описание терминов данного раздела смотрите в attributes(7).
┌─────────────────────────────────────────────────────┬──────────────────────┬──────────────────────────┐
│ Интерфейс │ Атрибут │ Значение │
├─────────────────────────────────────────────────────┼──────────────────────┼──────────────────────────┤
│ readdir() │ Безвредность в нитях │ MT-Unsafe race:dirstream │
└─────────────────────────────────────────────────────┴──────────────────────┴──────────────────────────┘
В текущей спецификации POSIX.1 (POSIX.1-2008), от readdir() не требуется быть нитебезопасной. Однако в
современных реализациях (включая glibc) параллельные вызовы readdir() для различных потоков каталога
являются нитебезопасными. В случаях, когда несколько нитей должны читать один поток каталога, всё равно
предпочтительней использовать readdir() с внешней синхронизацией, а не устаревшей readdir_r(3).
Ожидается, что в будущей версии POSIX.1 для readdir() будет требоваться нитебезопасность при
одновременной работе с разными потоками каталога.
ВЕРСИИ
В POSIX.1 определены только поля d_name и d_ino (расширение XSI). Кроме Linux, поле d_type доступно,
преимущественно только в системах BSD. Остальные поля доступны во многих, но не во всех системах. В glibc
программы могут определить доступность полей, не определённых в POSIX.1, по наличию макросов
_DIRENT_HAVE_D_NAMLEN, _DIRENT_HAVE_D_RECLEN, _DIRENT_HAVE_D_OFF или _DIRENT_HAVE_D_TYPE.
Поле d_name
Определение структуры dirent, показанное выше, взято из заголовочных файлов glibc и отражает поле d_name
с постоянным размером.
Warning: applications should avoid any dependence on the size of the d_name field. POSIX defines it as
char d_name[], a character array of unspecified size, with at most NAME_MAX characters preceding the
terminating null byte ('\0').
POSIX.1 explicitly notes that this field should not be used as an lvalue. The standard also notes that
the use of sizeof(d_name) is incorrect; use strlen(d_name) instead. (On some systems, this field is
defined as char d_name[1]!) By implication, the use sizeof(struct dirent) to capture the size of the
record including the size of d_name is also incorrect.
Заметим, что хотя вызов
fpathconf(fd, _PC_NAME_MAX)
и возвращает значение 255 в большинстве файловых систем, но в некоторых файловых системах (например,
CIFS, серверы Windows SMB) имя файла с null конце, возвращаемое (правильно) в d_name, может превышать
этот размер. В таких случаях поле d_reclen будет содержать значение, превышающее размер структуры glibc
dirent, показанной выше.
СТАНДАРТЫ
POSIX.1-2008.
ИСТОРИЯ
POSIX.1-2001, SVr4, 4.3BSD.
ПРИМЕЧАНИЯ
Поток каталога открывается с помощью opendir(3).
Порядок последовательно читаемых имён файлов вызовом readdir() зависит от реализации файловой системы; не
очень здорово, что имена будут отсортированы в непредсказуемом порядке.
СМОТРИТЕ ТАКЖЕ
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)
ПЕРЕВОД
Русский перевод этой страницы руководства разработал(и) aereiae <aereiae@gmail.com>, Azamat Hackimov
<azamat.hackimov@gmail.com>, Dmitriy S. Seregin <dseregin@59.ru>, Katrin Kutepova
<blackkatelv@gmail.com>, Lockal <lockalsash@gmail.com>, Yuri Kozlov <yuray@komyakino.ru>, Баринов
Владимир, Иван Павлов <pavia00@gmail.com> и Kirill Rekhov <krekhov.dev@gmail.com>
Этот перевод является свободной программной документацией; он распространяется на условиях общедоступной
лицензии GNU (GNU General Public License - GPL, https://www.gnu.org/licenses/gpl-3.0.html версии 3 или
более поздней) в отношении авторского права, но БЕЗ КАКИХ-ЛИБО ГАРАНТИЙ.
Если вы обнаружите какие-либо ошибки в переводе этой страницы руководства, пожалуйста, сообщите об этом
разработчику(ам) по его(их) адресу(ам) электронной почты или по адресу списка рассылки русских
переводчиков.
Справочные страницы Linux 6.9.1 16 июня 2024 г. readdir(3)