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:
- 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>.
- The d_reclen entry is the length, in
bytes, of the directory record.
- 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.
- The d_type is the type of the
file.
- 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 dir structure appeared in
Version 7 AT&T
UNIX. The
dirent structure appeared in
NetBSD 1.3.