DIR(5) FreeBSD File Formats Manual DIR(5)


dir, direntdirectory file format


#include < dirent.h>


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(2) and mount(8).)

The directory entry format is defined in the file < sys/dirent.h> (which should not be included directly by applications):

#ifndef _SYS_DIRENT_H_ 
#define _SYS_DIRENT_H_ 
#include <machine/ansi.h> 
 * The dirent structure defines the format of directory entries returned by 
 * the getdirentries(2) system call. 
 * A directory entry has a struct dirent at the front of it, containing its 
 * inode number, the length of the entry, and the length of the name 
 * contained in the entry.  These are followed by the name padded to a 4 
 * byte boundary with null bytes.  All names are guaranteed null terminated. 
 * The maximum length of a name in a directory is MAXNAMLEN. 
struct dirent { 
 __uint32_t d_fileno;  /* file number of entry */ 
 __uint16_t d_reclen;  /* length of this record */ 
 __uint8_t  d_type;   /* file type, see below */ 
 __uint8_t  d_namlen;  /* length of string in d_name */ 
 char d_name[255 + 1]; /* name must be no longer than this */ 
#define MAXNAMLEN 255 
 char d_name[MAXNAMLEN + 1]; /* name must be no longer than this */ 
 * File types 
#define DT_UNKNOWN  0 
#define DT_FIFO   1 
#define DT_CHR   2 
#define DT_DIR   4 
#define DT_BLK   6 
#define DT_REG   8 
#define DT_LNK  10 
#define DT_SOCK  12 
#define DT_WHT  14 
 * Convert between stat structure types and directory types. 
#define IFTODT(mode) (((mode) & 0170000) >> 12) 
#define DTTOIF(dirtype) ((dirtype) << 12) 
 * The _GENERIC_DIRSIZ macro gives the minimum record length which will hold 
 * the directory entry.  This requires the amount of space in struct direct 
 * without the d_name field, plus enough space for the name with a terminating 
 * null byte (dp->d_namlen+1), rounded up to a 4 byte boundary. 
#define _GENERIC_DIRSIZ(dp)     ((sizeof (struct dirent) - (MAXNAMLEN+1)) + (((dp)->d_namlen+1 + 3) &~ 3)) 
#ifdef _KERNEL 
#endif /* !_SYS_DIRENT_H_ */


fs(5), inode(5)


A dir file format appeared in Version 7 AT&T UNIX.


The usage of the member d_type of struct dirent is unportable as it is FreeBSD-specific. It also may fail on certain file systems, for example the cd9660 file system.
April 19, 1994 FreeBSD