2019-03-06
Aliases: readdir_r(3), readdir_r(3), readdir_r(3), readdir_r(3), readdir_r(3), readdir_r(3), readdir_r(3)
man-pages-ru
Russian man pages from the Linux Documentation Project
manpages-dev
Manual pages about using GNU/Linux for development
man-pages
Linux kernel and C library user-space interface documentation
ИМЯ
readdir - чтение содержимого каталога
ОБЗОР
#include <dirent.h>
struct dirent *readdir(DIR *dirp);
ОПИСАНИЕ
Функция readdir() возвращает указатель на структуру dirent, представляющую следующую запись каталога в потоке каталога, указанного в dirp. Функция возвращает NULL по достижении последней записи в потоке каталога или если произошла ошибка.
Данные, возвращаемые readdir(), могут быть переписаны последующими вызовами readdir() для того же потока каталога.
В реализации 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 в конце */ };
ino_t d_ino; /* номер иноды */
off_t d_off; /* не смещение, смотрите ниже */
unsigned short d_reclen; /* длина этой записи */
unsigned char d_type; /* тип файла; поддерживается
не во всех файловых системах */
char d_name[256]; /* имя файла с null в конце */ };
В соответствие с POSIX.1, структура dirent обязательно должна содержать поле d_name[] и d_ino. Другие поля не стандартизованы и имеются не во всех системах; подробней смотрите ЗАМЕЧАНИЯ далее.
Поля структуры dirent:
| d_ino | Номер иноды файла. | ||||||||||||||||
| d_off | Значение, возвращаемое в d_off, тоже самое что и после вызова telldir(3) в текущем положении курсора в потоке каталога. Учтите, что не смотря на тип и имя, в современных файловых системах поле d_off мало похоже на смещение в каталоге. Приложения должны считать, что это поле неизвестного типа(чёрным ящиком) и не делать предположений о его содержимом; смотрите также telldir(3). | ||||||||||||||||
| d_reclen | |||||||||||||||||
| Размер (в байтах) возвращаемой записи. Может не совпадать с размером структуры, показанной выше; смотрите ЗАМЕЧАНИЯ. | |||||||||||||||||
| d_type | Это поле содержит значение типа файла, что позволяет не делать дополнительный вызов lstat(2), если дальнейшие действия зависят от типа файла. | ||||||||||||||||
Если определён подходящий макрос тестирования свойств (_DEFAULT_SOURCE в версиях glibc начиная с 2.19 или _BSD_SOURCE в версиях glibc 2.19 и старее), то для значения, возвращаемого в d_type, glibc определяет следующие макросы-константы:
|
|||||||||||||||||
| В настоящее время, только файловые системы (среди которых: Btrfs, ext2, ext3 и ext4) поддерживают возврат типа файла в d_type. Все приложения должны правильно обрабатывать возвращаемое значение DT_UNKNOWN. | |||||||||||||||||
| d_name | Это поле содержит имя файла с завершающим null. Смотрите ЗАМЕЧАНИЯ. | ||||||||||||||||
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
При успешном выполнении readdir() возвращает указатель на структуру dirent (эта структура может выделяться статически; не пытайтесь освободить её с помощью free(3)).
При достижении конца потока каталога возвращается NULL и errno не изменяется. При возникновении ошибки возвращается NULL, а errno изменяется соответствующим образом. Чтобы отличить конец потока от ошибки присваивайте errno значение нуля перед вызовом readdir(), а после проверяйте значение errno, если возвращается NULL.
ОШИБКИ
| 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-2001, POSIX.1-2008, SVr4, 4.3BSD.
ЗАМЕЧАНИЯ
Поток каталога открывается с помощью opendir(3).
Порядок последовательно читаемых имён файлов вызовом 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 с постоянным размером.
Предупреждение: приложения не должны зависеть от размера поля d_name. В POSIX оно определено как char d_name[], массив символов неопределённого размера, не более NAME_MAX символов с конечным байтом null (\(aq\0\(aq).
В POSIX.1 явно сказано, что это поле не должно использоваться как lvalue. В стандарте также отмечено, что использование sizeof(d_name) некорректно; вместо него используйте strlen(d_name) (в некоторых системах это поле определено как char d_name[1]!). Как следствие, использовать sizeof(struct dirent) для получения размера записи, включающей размер d_name также неправильно.
Заметим, что хотя вызов
fpathconf(fd, _PC_NAME_MAX)
и возвращает значение 255 в большинстве файловых систем, но в некоторых файловых системах (например, CIFS, серверы Windows SMB) имя файла с null конце, возвращаемое (правильно) в d_name, может превышать этот размер. В таких случаях поле d_reclen будет содержать значение, превышающее размер структуры glibc dirent, показанной выше.
