1.\" Copyright (c) 1983, 1991, 1993 2.\" The Regents of the University of California. All rights reserved. 3.\" 4.\" %sccs.include.redist.man% 5.\" 6.\" @(#)dir.5 8.4 (Berkeley) 05/03/95 7.\" 8.Dd 9.Dt DIR 5 10.Os BSD 4.2 11.Sh NAME 12.Nm dir , 13.Nm dirent 14.Nd directory file format 15.Sh SYNOPSIS 16.Fd #include <sys/types.h> 17.Fd #include <sys/dir.h> 18.Sh DESCRIPTION 19Directories provide a convenient hierarchical method of grouping 20files while obscuring the underlying details of the storage medium. 21A directory file is differentiated from a plain file 22by a flag in its 23.Xr inode 5 24entry. 25It consists of records (directory entries) each of which contains 26information about a file and a pointer to the file itself. 27Directory entries may contain other directories 28as well as plain files; such nested directories are refered to as 29subdirectories. 30A hierarchy of directories and files is formed in this manner 31and is called a file system (or referred to as a file system tree). 32.\" An entry in this tree, 33.\" nested or not nested, 34.\" is a pathname. 35.Pp 36Each directory file contains two special directory entries; one is a pointer 37to the directory itself 38called dot 39.Ql \&. 40and the other a pointer to its parent directory called dot-dot 41.Ql \&.. . 42Dot and dot-dot 43are valid pathnames, however, 44the system root directory 45.Ql / , 46has no parent and dot-dot points to itself like dot. 47.Pp 48File system nodes are ordinary directory files on which has 49been grafted a file system object, such as a physical disk or a 50partitioned area of such a disk. 51(See 52.Xr mount 1 53and 54.Xr mount 8 . ) 55.Pp 56The directory entry format is defined in the file 57.Aq dirent.h : 58.Bd -literal 59#ifndef _DIRENT_H_ 60#define _DIRENT_H_ 61 62/* 63 * The dirent structure defines the format of directory entries returned by 64 * the getdirentries(2) system call. 65 * 66 * A directory entry has a struct dirent at the front of it, containing its 67 * inode number, the length of the entry, and the length of the name 68 * contained in the entry. These are followed by the name padded to a 4 69 * byte boundary with null bytes. All names are guaranteed null terminated. 70 * The maximum length of a name in a directory is MAXNAMLEN. 71 */ 72 73struct dirent { 74 u_int32_t d_fileno; /* file number of entry */ 75 u_int16_t d_reclen; /* length of this record */ 76 u_int8_t d_type; /* file type, see below */ 77 u_int8_t d_namlen; /* length of string in d_name */ 78#ifdef _POSIX_SOURCE 79 char d_name[255 + 1]; /* name must be no longer than this */ 80#else 81#define MAXNAMLEN 255 82 char d_name[MAXNAMLEN + 1]; /* name must be no longer than this */ 83#endif 84}; 85 86/* 87 * File types 88 */ 89#define DT_UNKNOWN 0 90#define DT_FIFO 1 91#define DT_CHR 2 92#define DT_DIR 4 93#define DT_BLK 6 94#define DT_REG 8 95#define DT_LNK 10 96#define DT_SOCK 12 97#define DT_WHT 14 98 99/* 100 * Convert between stat structure types and directory types. 101 */ 102#define IFTODT(mode) (((mode) & 0170000) >> 12) 103#define DTTOIF(dirtype) ((dirtype) << 12) 104 105#ifdef _POSIX_SOURCE 106typedef void * DIR; 107#else 108 109#define d_ino d_fileno /* backward compatibility */ 110 111/* definitions for library routines operating on directories. */ 112#define DIRBLKSIZ 1024 113 114/* structure describing an open directory. */ 115typedef struct _dirdesc { 116 int dd_fd; /* file descriptor associated with directory */ 117 long dd_loc; /* offset in current buffer */ 118 long dd_size; /* amount of data returned by getdirentries */ 119 char *dd_buf; /* data buffer */ 120 int dd_len; /* size of data buffer */ 121 long dd_seek; /* magic cookie returned by getdirentries */ 122 long dd_rewind; /* magic cookie for rewinding */ 123 int dd_flags; /* flags for readdir */ 124} DIR; 125 126#define dirfd(dirp) ((dirp)->dd_fd) 127 128/* flags for opendir2 */ 129#define DTF_HIDEW 0x0001 /* hide whiteout entries */ 130#define DTF_NODUP 0x0002 /* don't return duplicate names */ 131#define DTF_REWIND 0x0004 /* rewind after reading union stack */ 132#define __DTF_READALL 0x0008 /* everything has been read */ 133 134#ifndef NULL 135#define NULL 0 136#endif 137 138#endif /* _POSIX_SOURCE */ 139 140#ifndef KERNEL 141 142#include <sys/cdefs.h> 143 144__BEGIN_DECLS 145DIR *opendir __P((const char *)); 146struct dirent *readdir __P((DIR *)); 147void rewinddir __P((DIR *)); 148int closedir __P((DIR *)); 149#ifndef _POSIX_SOURCE 150DIR *__opendir2 __P((const char *, int)); 151long telldir __P((const DIR *)); 152void seekdir __P((DIR *, long)); 153int scandir __P((const char *, struct dirent ***, 154 int (*)(struct dirent *), int (*)(const void *, const void *))); 155int alphasort __P((const void *, const void *)); 156int getdirentries __P((int, char *, int, long *)); 157#endif /* not POSIX */ 158__END_DECLS 159 160#endif /* !KERNEL */ 161 162#endif /* !_DIRENT_H_ */ 163.Ed 164.Sh SEE ALSO 165.Xr fs 5 166.Xr inode 5 167.Sh HISTORY 168A 169.Nm 170file format appeared in 171.At v7 . 172