Directory Entries (The GNU C Library)

#### 14.3.1 Format of a Directory Entry ¶

This section describes what you find in a single directory entry, as you might obtain it from a directory stream. All the symbols are declared in the header file `dirent.h`.

Data Type: struct dirent ¶

  This is a structure type used to return information about directory entries. It contains the following fields:

  `char d_name[]`

    This is the null-terminated file name component. This is the only field you can count on in all POSIX systems.

    While this field is defined with a specified length, functions such as `readdir` may return a pointer to a `struct dirent` where the `d_name` extends beyond the end of the struct.

  `ino_t d_fileno`

    This is the file serial number. For BSD compatibility, you can also refer to this member as `d_ino`. On GNU/Linux and GNU/Hurd systems and most POSIX systems, for most files this the same as the `st_ino` member that `stat` will return for the file. See File Attributes.

  `off_t d_off`

    This value contains the offset of the next directory entry (after this entry) in the directory stream. The value may not be compatible with `lseek` or `seekdir`, especially if the width of `d_off` is less than 64 bits. Directory entries are not ordered by offset, and the `d_off` and `d_reclen` values are unrelated. Seeking on directory streams is not recommended. The symbol `_DIRENT_HAVE_D_OFF` is defined if the `d_ino` member is available.

  `unsigned char d_namlen`

    This is the length of the file name, not including the terminating null character. Its type is `unsigned char` because that is the integer type of the appropriate size. This member is a BSD extension. The symbol `_DIRENT_HAVE_D_NAMLEN` is defined if this member is available. (It is not available on Linux.)

  `unsigned short int d_reclen`

    This is the length of the entire directory record. When iterating through a buffer filled by `getdents64` (see Low-level Directory Access), this value needs to be added to the offset of the current directory entry to obtain the offset of the next entry. When using `readdir` and related functions, the value of `d_reclen` is undefined and should not be accessed. The symbol `_DIRENT_HAVE_D_RECLEN` is defined if this member is available.

  `unsigned char d_type`

    This is the type of the file, possibly unknown. The following constants are defined for its value:

    `DT_UNKNOWN` ¶

      The type is unknown. Only some filesystems have full support to return the type of the file, others might always return this value.

    `DT_REG` ¶

      A regular file.

    `DT_DIR` ¶

      A directory.

    `DT_FIFO` ¶

      A named pipe, or FIFO. See FIFO Special Files.

    `DT_SOCK` ¶

      A local-domain socket.

    `DT_CHR` ¶

      A character device.

    `DT_BLK` ¶

      A block device.

    `DT_LNK` ¶

      A symbolic link.

    This member is a BSD extension. The symbol `_DIRENT_HAVE_D_TYPE` is defined if this member is available. On systems where it is used, it corresponds to the file type bits in the `st_mode` member of `struct stat`. If the value cannot be determined the member value is `DT_UNKNOWN`. These two macros convert between `d_type` values and `st_mode` values:

    Function: `int` IFTODT `(mode_t mode)` ¶

      Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

      This returns the `d_type` value corresponding to mode.

    Function: `mode_t` DTTOIF `(int dtype)` ¶

      Preliminary: | MT-Safe | AS-Safe | AC-Safe | See POSIX Safety Concepts.

      This returns the `st_mode` value corresponding to dtype.

  This structure may contain additional members in the future. Their availability is always announced in the compilation environment by a macro named `_DIRENT_HAVE_D_xxx` where xxx is replaced by the name of the new member. For instance, the member `d_reclen` available on some systems is announced through the macro `_DIRENT_HAVE_D_RECLEN`.

  When a file has multiple names, each name has its own directory entry. The only way you can tell that the directory entries belong to a single file is that they have the same value for the `d_fileno` field.

  File attributes such as size, modification times etc., are part of the file itself, not of any particular directory entry. See File Attributes.