NAME

dirent.h — format of directory entries

SYNOPSIS

#include <dirent.h>

DESCRIPTION

The internal format of directories is unspecified.

The <dirent.h> header shall define the following type:

DIR

A type representing a directory stream. The DIR type may be an incomplete type.

It shall also define the structure dirent which shall include the following members:

ino_t  d_ino       File serial number.
char   d_name[]    Filename string of entry.

and the structure posix_dent which shall include the following members:

ino_t          d_ino      File serial number.
reclen_t       d_reclen   Length of this entry, including trailing
                          padding if necessary. See posix_getdents().
unsigned char  d_type     File type or unknown-file-type indication.
char           d_name[]   Filename string of this entry.

The array d_name in each of these structures is of unspecified size, but shall contain a filename of at most {NAME_MAX} bytes followed by a terminating null byte.

The <dirent.h> header shall define the ino_t, reclen_t, size_t, and ssize_t types as described in <sys/types.h>.

The <dirent.h> header shall define the following symbolic constants for the file types and unknown-file-type indicator returned in the d_type member of the posix_dent structure. The values shall be distinct and shall be suitable for use in #if preprocessing directives:

DT_BLK

Block special.

DT_CHR

Character special.

DT_DIR

Directory.

DT_FIFO

FIFO special.

DT_LNK

Symbolic link.

DT_REG

Regular.

DT_SOCK

Socket.

DT_UNKNOWN

Unknown file type.

The implementation may implement message queues, semaphores, shared memory objects ^[TYM]  or typed memory objects  as distinct file types. The following macros shall be provided to represent these types. The values shall be distinct from each other and from the above symbolic constants beginning with DT_, except when a distinct file type is not implemented, in which case the corresponding constant shall have a value that is never returned in d_type by posix_getdents(). The values shall be suitable for use in #if preprocessing directives:

DT_MQ

Message queue.

DT_SEM

Semaphore.

DT_SHM

Shared memory object.

DT_TMO

^[TYM] Typed memory object.

The following shall be declared as functions and may also be defined as macros. Function prototypes shall be provided.

int            alphasort(const struct dirent **, const struct dirent **);
int            closedir(DIR *);
int            dirfd(DIR *);
DIR           *fdopendir(int);
DIR           *opendir(const char *);
ssize_t        posix_getdents(int, void *, size_t, int);
struct dirent *readdir(DIR *);
[OB]
int            readdir_r(DIR *restrict, struct dirent *restrict,
                   struct dirent **restrict);

void           rewinddir(DIR *);
int            scandir(const char *, struct dirent ***,
                   int (*)(const struct dirent *),
                   int (*)(const struct dirent **,
                   const struct dirent **));
[XSI]
void           seekdir(DIR *, long);
long           telldir(DIR *);

APPLICATION USAGE

None.

RATIONALE

Information similar to that in the <dirent.h> header is contained in a file <sys/dir.h> in 4.2 BSD and 4.3 BSD. The equivalent in these implementations of struct dirent from this volume of POSIX.1-2024 is struct direct. The filename was changed because the name <sys/dir.h> was also used in earlier implementations to refer to definitions related to the older access method; this produced name conflicts. The name of the structure was changed because this volume of POSIX.1-2024 does not completely define what is in the structure, so it could be different on some implementations from struct direct.

The posix_dent structure was based on existing structures used by traditional getdents() functions, but the name was changed because the existing structures differed in name and in their members. Some used the dirent structure but this is not required to include a d_type member, which is the main advantage of using posix_getdents() over readdir(). The d_reclen member was included, even though some implementations return fixed-length entries and therefore do not need it, as almost all existing code that used getdents() used d_reclen to iterate through the returned entries. Implementations that return fixed-length entries can simply set d_reclen to that length in posix_getdents(). The type reclen_t for d_reclen was introduced, instead of using unsigned short, so as not to create a requirement that {NAME_MAX} cannot be greater than (a value somewhat smaller than) {SHRT_MAX}.

Implementations are encouraged to define a DT_FORCE_TYPE symbolic constant for use in the flags argument to posix_getdents(). See the RATIONALE for posix_getdents.

The name of an array of char of an unspecified size should not be used as an lvalue. Use of:

sizeof(d_name)

is incorrect; use:

strlen(d_name)

instead.

The array of char d_name cannot be assumed to have a fixed size. Implementations may define the d_name array in the dirent and posix_dent structures to have size 1, or size greater than {NAME_MAX}, or use a flexible array member, but in all cases the actual number of characters used for d_name is at least the length of the filename string including the terminating NUL byte.

FUTURE DIRECTIONS

A future version of this standard may add a DT_FORCE_TYPE symbolic constant for use as described in the RATIONALE for posix_getdents.

SEE ALSO

<sys/types.h>

XSH alphasort, closedir, dirfd, fdopendir, posix_getdents, readdir, rewinddir, seekdir, telldir

CHANGE HISTORY

First released in Issue 2.

Issue 5

The DESCRIPTION is updated for alignment with the POSIX Threads Extension.

Issue 6

The Open Group Corrigendum U026/7 is applied, correcting the prototype for readdir_r().

The restrict keyword is added to the prototype for readdir_r().

Issue 7

The alphasort(), dirfd(), and scandir() functions are added from The Open Group Technical Standard, 2006, Extended API Set Part 1.

The fdopendir() function is added from The Open Group Technical Standard, 2006, Extended API Set Part 2.

Austin Group Interpretation 1003.1-2001 #110 is applied, clarifying the definition of the DIR type.

POSIX.1-2008, Technical Corrigendum 1, XBD/TC1-2008/0039 [291], XBD/TC1-2008/0040 [291], XBD/TC1-2008/0041 [291], and XBD/TC1-2008/0042 [206] are applied.

Issue 8

Austin Group Defect 696 is applied, making readdir_r() obsolescent.

Austin Group Defect 697 is applied, adding posix_getdents().