Updated: 2022/Sep/29

Please read Privacy Policy. It's for your privacy.

DIRENT(3)                  Library Functions Manual                  DIRENT(3)

NAME
     dirent - directory format

SYNOPSIS
     #include <sys/types.h>
     #include <sys/dirent.h>

     mode
     DTTOIF(dirtype);

     dirtype
     IFTODT(mode);

DESCRIPTION
     Directories provide a convenient hierarchical method of grouping files
     while obscuring the underlying details of the storage medium.  A
     directory file is differentiated from a plain file by a flag in its
     inode(5) entry.  It consists of records (directory entries) each of which
     contains information about a file and a pointer to the file itself.
     Directory entries may contain other directories as well as plain files;
     such nested directories are referred to as subdirectories.  A hierarchy
     of directories and files is formed in this manner and is called a file
     system (or referred to as a file system tree).

     Each directory file contains two special directory entries; one is a
     pointer to the directory itself called dot `.' and the other a pointer to
     its parent directory called dot-dot `..'.  Dot and dot-dot are valid
     pathnames, however, the system root directory `/', has no parent and dot-
     dot points to itself like dot.

     File system nodes are ordinary directory files on which has been grafted
     a file system object, such as a physical disk or a partitioned area of
     such a disk.  (See mount(8).)

IMPLEMENTATION NOTES
     The directory entry format is defined in the file <sys/dirent.h>, which
     is also included by <dirent.h>.  The format is represented by the dirent
     structure, which contains the following entries:

           ino_t           d_fileno;
           uint16_t        d_reclen;
           uint16_t        d_namlen;
           uint8_t         d_type;
           char            d_name[MAXNAMLEN + 1];

     These are:

           1.   The d_fileno entry is a number which is unique for each
                distinct file in the filesystem.  Files that are linked by
                hard links (see link(2)) have the same d_fileno.  If d_fileno
                is zero, the entry refers to a deleted file.  The type ino_t
                is defined in <sys/types.h>.

           2.   The d_reclen entry is the length, in bytes, of the directory
                record.

           3.   The d_namlen entry specifies the length of the file name
                excluding the NUL.  Thus the actual size of d_name may vary
                from 1 to MAXNAMLEN + 1.

           4.   The d_type is the type of the file.

           5.   The d_name entry contains a NUL-terminated file name.

     The following table lists the types available for d_type and the
     corresponding ones used in the struct stat (see stat(2)), respectively:

           Dirent         Stat           Description
           DT_UNKNOWN     -              unknown file type
           DT_FIFO        S_IFIFO        named pipe
           DT_CHR         S_IFCHR        character device
           DT_DIR         S_IFDIR        directory
           DT_BLK         S_IFBLK        block device
           DT_REG         S_IFREG        regular file
           DT_LNK         S_IFLNK        symbolic link
           DT_SOCK        S_IFSOCK       UNIX domain socket
           DT_WHT         S_IFWHT        dummy "whiteout inode"

     The DT_WHT type is internal to the implementation and should not be seen
     in normal user applications.  The macros DTTOIF() and IFTODT() can be
     used to convert from struct dirent types to struct stat types, and vice
     versa.

COMPATIBILITY
     The IEEE Std 1003.1-2001 ("POSIX.1") standard specifies only the fields
     d_ino and d_name.  The remaining fields are available on many, but not
     all systems.

     Furthermore, the standard leaves the size of d_name as unspecified,
     mentioning only that the number of bytes preceding the terminating NUL
     shall not exceed NAME_MAX.  Because of this, and because the d_namlen
     field may not be present, a portable application should determine the
     size of d_name by using strlen(3) instead of applying the sizeof()
     operator.

SEE ALSO
     getdents(2), fs(5), inode(5)

HISTORY
     A directory file format appeared in Version 1 AT&T UNIX.  The dirent
     structure appeared in 4.3BSD-Reno.

NetBSD 10.99                   September 7, 2019                  NetBSD 10.99