Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
DIRENT(3)		 BSD Library Functions Manual		     DIRENT(3)

     dirent -- directory format

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



     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 en-
     tries 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).)

     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

	   3.	The d_namlen entry specifies the length	of the file name ex-
		cluding	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

     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.

     getdents(2), fs(5), inode(5)

     A dir structure appeared in Version 7 AT&T	UNIX.  The dirent structure
     appeared in NetBSD	1.3.

BSD				 May 16, 2010				   BSD


Want to link to this manual page? Use this URL:

home | help