dirent(3) - NetBSD Manual Pages

DIRENT(3)               NetBSD 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 direc-
     tory 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 directo-
     ries 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 dis-
                tinct 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 corre-
     sponding 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, men-
     tioning 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 dir structure appeared in Version 7 AT&T UNIX.  The dirent structure
     appeared in NetBSD 1.3.

NetBSD 9.3                       May 16, 2010                       NetBSD 9.3