DIRENT(3)

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.

September 7, 2019 | NetBSD 10.1