1.\" $OpenBSD: dir.5,v 1.18 2014/01/21 03:15:46 schwarze 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.4 (Berkeley) 5/3/95 31.\" 32.Dd $Mdocdate: January 21 2014 $ 33.Dt DIR 5 34.Os 35.Sh NAME 36.Nm dir , 37.Nm dirent 38.Nd directory file format 39.Sh SYNOPSIS 40.Fd #include <dirent.h> 41.Sh DESCRIPTION 42Directories provide a convenient hierarchical method of grouping 43files while obscuring the underlying details of the storage medium. 44A directory file is differentiated from a plain file by a flag in its 45.Xr inode 5 46entry. 47It consists of records (directory entries) each of which contains 48information about a file and a pointer to the file itself. 49Directory entries may contain other directories as well as plain files; 50such nested directories are referred to as subdirectories. 51A hierarchy of directories and files is formed in this manner 52and is called a file system (or referred to as a file system tree). 53.\" An entry in this tree, 54.\" nested or not nested, 55.\" is a pathname. 56.Pp 57Each directory file contains two special directory entries; one is a pointer 58to the directory itself called dot 59.Pq Dq \&. 60and the other a pointer to its parent directory called dot-dot 61.Pq Dq \&.. . 62Dot and dot-dot are valid pathnames, however, the system root directory 63.Pq Dq / , 64has no parent and dot-dot points to itself like dot. 65.Pp 66File system nodes are ordinary directory files on which has 67been grafted a file system object, such as a physical disk or a 68partitioned area of such a disk (see 69.Xr mount 8 ) . 70.Pp 71The directory entry format is defined in the file 72.In dirent.h : 73.Bd -literal 74/* 75 * A directory entry has a struct dirent at the front of it, containing 76 * its inode number, the length of the entry, and the length of the name 77 * contained in the entry. These are followed by the name padded to some 78 * alignment (currently 8 bytes) with NUL bytes. All names are guaranteed 79 * NUL terminated. The maximum length of a name in a directory is MAXNAMLEN. 80 */ 81 82struct dirent { 83 ino_t d_fileno; /* file number of entry */ 84 off_t d_off; /* offset of next entry */ 85 u_int16_t d_reclen; /* length of this record */ 86 u_int8_t d_type; /* file type, see below */ 87 u_int8_t d_namlen; /* length of string in d_name */ 88#define MAXNAMLEN 255 89 char d_name[MAXNAMLEN + 1]; /* maximum name length */ 90}; 91 92#define d_ino d_fileno /* backward compatibility */ 93 94/* 95 * File types 96 */ 97#define DT_UNKNOWN 0 98#define DT_FIFO 1 99#define DT_CHR 2 100#define DT_DIR 4 101#define DT_BLK 6 102#define DT_REG 8 103#define DT_LNK 10 104#define DT_SOCK 12 105.Ed 106.Sh SEE ALSO 107.Xr getdents 2 , 108.Xr fs 5 , 109.Xr inode 5 110.Sh HISTORY 111A 112.Nm dir 113file format appeared in 114.At v7 . 115The 116.Fa d_off 117member was added in 118.Ox 5.5 . 119