1.\" $NetBSD: dirent.3,v 1.7 2021/08/12 20:25:26 andvar Exp $ 2.\" 3.\" Copyright (c) 1983, 1991, 1993 4.\" The Regents of the University of California. All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 1. Redistributions of source code must retain the above copyright 10.\" notice, this list of conditions and the following disclaimer. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice, this list of conditions and the following disclaimer in the 13.\" documentation and/or other materials provided with the distribution. 14.\" 3. Neither the name of the University nor the names of its contributors 15.\" may be used to endorse or promote products derived from this software 16.\" without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND 19.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 20.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 21.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE 22.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 23.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 24.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 25.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 26.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 27.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 28.\" SUCH DAMAGE. 29.\" 30.\" @(#)dir.5 8.3 (Berkeley) 4/19/94 31.\" 32.Dd September 7, 2019 33.Dt DIRENT 3 34.Os 35.Sh NAME 36.Nm dirent 37.Nd directory format 38.Sh SYNOPSIS 39.In sys/types.h 40.In sys/dirent.h 41.Ft mode 42.Fn DTTOIF "dirtype" 43.Ft dirtype 44.Fn IFTODT "mode" 45.Sh DESCRIPTION 46Directories provide a convenient hierarchical method of grouping 47files while obscuring the underlying details of the storage medium. 48A directory file is differentiated from a plain file 49by a flag in its 50.Xr inode 5 51entry. 52It consists of records (directory entries) each of which contains 53information about a file and a pointer to the file itself. 54Directory entries may contain other directories 55as well as plain files; such nested directories are referred to as 56subdirectories. 57A hierarchy of directories and files is formed in this manner 58and is called a file system (or referred to as a file system tree). 59.\" An entry in this tree, 60.\" nested or not nested, 61.\" is a pathname. 62.Pp 63Each directory file contains two special directory entries; one is a pointer 64to the directory itself 65called dot 66.Ql \&. 67and the other a pointer to its parent directory called dot-dot 68.Ql \&.. . 69Dot and dot-dot 70are valid pathnames, however, 71the system root directory 72.Ql / , 73has no parent and dot-dot points to itself like dot. 74.Pp 75File system nodes are ordinary directory files on which has 76been grafted a file system object, such as a physical disk or a 77partitioned area of such a disk. 78(See 79.Xr mount 8 . ) 80.Sh IMPLEMENTATION NOTES 81The directory entry format is defined in the file 82.In sys/dirent.h , 83which is also included by 84.In dirent.h . 85The format is represented by the 86.Em dirent 87structure, which contains the following entries: 88.Bd -literal -offset indent 89ino_t d_fileno; 90uint16_t d_reclen; 91uint16_t d_namlen; 92uint8_t d_type; 93char d_name[MAXNAMLEN + 1]; 94.Ed 95.Pp 96These are: 97.Bl -enum -offset indent 98.It 99The 100.Fa d_fileno 101entry is a number which is unique for each 102distinct file in the filesystem. 103Files that are linked by hard links (see 104.Xr link 2 ) 105have the same 106.Fa d_fileno . 107If 108.Fa d_fileno 109is zero, the entry refers to a deleted file. 110The type 111.Va ino_t 112is defined in 113.In sys/types.h . 114.It 115The 116.Fa d_reclen 117entry is the length, in bytes, of the directory record. 118.It 119The 120.Fa d_namlen 121entry specifies the length of the file name excluding the NUL. 122Thus the actual size of 123.Fa d_name 124may vary from 1 to 125.Dv MAXNAMLEN 126\&+ 1. 127.It 128The 129.Fa d_type 130is the type of the file. 131.It 132The 133.Fa d_name 134entry contains a NUL-terminated file name. 135.El 136.Pp 137The following table lists the types available for 138.Vt d_type 139and the corresponding ones used in the 140.Em struct stat 141(see 142.Xr stat 2 ) , 143respectively: 144.Pp 145.Bl -column -offset indent -compact \ 146"DT_UNKNOWN " "DT_UNKNOWN " "DT_UNKNOWN " 147.It Sy Dirent Ta Sy Stat Ta Sy Description 148.It Dv DT_UNKNOWN Ta - Ta unknown file type 149.It Dv DT_FIFO Ta Dv S_IFIFO Ta named pipe 150.It Dv DT_CHR Ta Dv S_IFCHR Ta character device 151.It Dv DT_DIR Ta Dv S_IFDIR Ta directory 152.It Dv DT_BLK Ta Dv S_IFBLK Ta block device 153.It Dv DT_REG Ta Dv S_IFREG Ta regular file 154.It Dv DT_LNK Ta Dv S_IFLNK Ta symbolic link 155.It Dv DT_SOCK Ta Dv S_IFSOCK Ta UNIX domain socket 156.It Dv DT_WHT Ta Dv S_IFWHT Ta dummy Dq whiteout inode 157.El 158.Pp 159The 160.Dv DT_WHT 161type is internal to the implementation and 162should not be seen in normal user applications. 163The macros 164.Fn DTTOIF 165and 166.Fn IFTODT 167can be used to convert from 168.Em struct dirent 169types to 170.Em struct stat 171types, and vice versa. 172.Sh COMPATIBILITY 173The 174.St -p1003.1-2001 175standard specifies only the fields 176.Va d_ino 177and 178.Va d_name . 179The remaining fields are available on many, but not all systems. 180.Pp 181Furthermore, the standard leaves the size of 182.Va d_name 183as unspecified, mentioning only that the number of 184bytes preceding the terminating NUL shall not exceed 185.Dv NAME_MAX . 186Because of this, and because the 187.Va d_namlen 188field may not be present, a portable application should determine the size of 189.Va d_name 190by using 191.Xr strlen 3 192instead of applying the 193.Fn sizeof 194operator. 195.Sh SEE ALSO 196.Xr getdents 2 , 197.Xr fs 5 , 198.Xr inode 5 199.\" .Sh STANDARDS 200.\" 201.\" XXX: Conformance is unclear, cf. PR lib/43310. 202.\" 203.\" Given the noted limitations, the 204.\".In dirent.h 205.\" header conforms to 206.\" .St -p1003.1-2001 . 207.Sh HISTORY 208A 209directory file format appeared in 210.At v1 . 211The 212.Em dirent 213structure appeared in 214.Bx 4.3 reno . 215