dirent, dirent64

Updated: May 06, 2022

Data structure for a directory entry

Synopsis:

#include <dirent.h>

struct dirent {
#if __OFF_BITS__ == 64
        ino_t                   d_ino;
        off_t                   d_offset;
#elif __OFF_BITS__ == 32
# if defined(__LITTLEENDIAN__)
        ino_t                   d_ino;
        ino_t                   d_ino_hi;
        off_t                   d_offset;
        off_t                   d_offset_hi;
# elif defined(__BIGENDIAN__)
        ino_t                   d_ino_hi;
        ino_t                   d_ino;
        off_t                   d_offset_hi;
        off_t                   d_offset;
# else
#  error endian not configured for system
# endif
#else
# error __OFF_BITS__ value is unsupported
#endif
        int16_t                 d_reclen;
        int16_t                 d_namelen;
        char                    d_name[1]);
};

#ifdef __EXT_LF64SRC
struct dirent64 {
        ino64_t                 d_ino;
        off64_t                 d_offset;
        int16_t                 d_reclen;
        int16_t                 d_namelen;
        char                    d_name[1]);
};
#endif

Description:

The dirent structure describes an entry in a directory. The dirent64 structure is for large-file support.

Note: The large-file support functions and data types appear in the name space only if you define _LARGEFILE64_SOURCE when you compile your code. For more information, see Classification in What's in a Function Description?

The members include:

d_ino
A mountpoint-unique file serial number. This serial number is often used in various disk-checking utilities for such operations as determining infinite-loop directory links. (Note that the inode value cannot be zero, which would indicate that the inode represents an unused entry.)
d_offset
In some filesystems, this member identifies the directory entry itself; in others, it's the offset of the next directory entry. For a disk-based filesystem, this value might be the actual offset into the on-disk directory structure.
d_reclen
The size of this directory entry including the name and any other associated information (such as an optional struct stat structure appended to the struct dirent entry).
d_namelen
The length of the name not including the \0 string terminator. The terminator must be present, but isn't counted.
d_name
The actual name of that directory entry.
Note:

These structures provide d_name as a place-holder for the start of the name, but do not supply storage for more than the leading bytes in the name.

If using readdir(), the dirent structures returned by this function supply enough space to hold the entire name.

If using readdir_r(), you must supply an appropriate buffer for the dirent including name. This buffer size (in bytes) is always large enough:
offsetof(struct dirent, d_name) + PATH_MAX
If handling readdir() requests in a resource manager, you must generate appropriate variable-length entries to return to the client. See Returning directory entries from _IO_READ in Writing a Resource Manager.

Classification:

dirent is POSIX 1003.1; dirent64 is Large-file support