DIRENT(3) BSD Library Functions Manual DIRENT(3)NAMEdirent — 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 ALSOgetdents(2), fs(5), inode(5)HISTORY
A dir structure appeared in Version 7 AT&T UNIX. The dirent structure
appeared in NetBSD 1.3.
BSD May 16, 2010 BSD
