DIRENT(3)

💖 dirent — directory format 💖

bestie, this is dirent(3) from the Library Functions Manual (section 3), and it’s literally the directory format page. We’re decoding it together. 🫶

---

🌸 NAME 🌸

dirent — directory format. That’s it, that’s the name. 💅

---

✨ SYNOPSIS ✨

The synopsis is literally this, no cap:

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

mode
DTTOIF(dirtype);

dirtype
IFTODT(mode);

---

🦋 DESCRIPTION 🦋

okay so bestie, directories are a convenient hierarchical way to group 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 is 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 list maps the types available for d_type to the corresponding ones used in the struct stat (see stat(2)), respectively:

• DT_UNKNOWN — stat: - — unknown file type
• DT_FIFO — stat: S_IFIFO — named pipe
• DT_CHR — stat: S_IFCHR — character device
• DT_DIR — stat: S_IFDIR — directory
• DT_BLK — stat: S_IFBLK — block device
• DT_REG — stat: S_IFREG — regular file
• DT_LNK — stat: S_IFLNK — symbolic link
• DT_SOCK — stat: S_IFSOCK — UNIX domain socket
• DT_WHT — stat: 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. 🎀

---

mwah! 💋 this page is from the Debian version, dated September 7, 2019 — source/version and date, right there in the cutest little sign-off. 💅✨