Return to dir.5 CVS log

Up to [DragonFly] / src / share / man / man5

Add the DragonFly cvs id and perform general cleanups on cvs/rcs/sccs ids.  Most
ids have been removed from !lint sections and moved into comment sections.

    1: .\" Copyright (c) 1983, 1991, 1993
    2: .\"	The Regents of the University of California.  All rights reserved.
    3: .\"
    4: .\" Redistribution and use in source and binary forms, with or without
    5: .\" modification, are permitted provided that the following conditions
    6: .\" are met:
    7: .\" 1. Redistributions of source code must retain the above copyright
    8: .\"    notice, this list of conditions and the following disclaimer.
    9: .\" 2. Redistributions in binary form must reproduce the above copyright
   10: .\"    notice, this list of conditions and the following disclaimer in the
   11: .\"    documentation and/or other materials provided with the distribution.
   12: .\" 3. All advertising materials mentioning features or use of this software
   13: .\"    must display the following acknowledgement:
   14: .\"	This product includes software developed by the University of
   15: .\"	California, Berkeley and its contributors.
   16: .\" 4. Neither the name of the University nor the names of its contributors
   17: .\"    may be used to endorse or promote products derived from this software
   18: .\"    without specific prior written permission.
   19: .\"
   20: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
   21: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
   22: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
   23: .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
   24: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
   25: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
   26: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
   27: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
   28: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
   29: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
   30: .\" SUCH DAMAGE.
   31: .\"
   32: .\"     @(#)dir.5	8.3 (Berkeley) 4/19/94
   33: .\" $FreeBSD: src/share/man/man5/dir.5,v 1.12.2.5 2001/12/17 11:30:13 ru Exp $
   34: .\" $DragonFly: src/share/man/man5/dir.5,v 1.2 2003/06/17 04:37:00 dillon Exp $
   35: .\"
   36: .Dd April 19, 1994
   37: .Dt DIR 5
   38: .Os
   39: .Sh NAME
   40: .Nm dir ,
   41: .Nm dirent
   42: .Nd directory file format
   43: .Sh SYNOPSIS
   44: .In dirent.h
   45: .Sh DESCRIPTION
   46: Directories provide a convenient hierarchical method of grouping
   47: files while obscuring the underlying details of the storage medium.
   48: A directory file is differentiated from a plain file
   49: by a flag in its
   50: .Xr inode 5
   51: entry.
   52: It consists of records (directory entries) each of which contains
   53: information about a file and a pointer to the file itself.
   54: Directory entries may contain other directories
   55: as well as plain files; such nested directories are referred to as
   56: subdirectories.
   57: A hierarchy of directories and files is formed in this manner
   58: and 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
   63: Each directory file contains two special directory entries; one is a pointer
   64: to the directory itself
   65: called dot
   66: .Ql .\&
   67: and the other a pointer to its parent directory called dot-dot
   68: .Ql \&.. .
   69: Dot and dot-dot
   70: are valid pathnames, however,
   71: the system root directory
   72: .Ql / ,
   73: has no parent and dot-dot points to itself like dot.
   74: .Pp
   75: File system nodes are ordinary directory files on which has
   76: been grafted a file system object, such as a physical disk or a
   77: partitioned area of such a disk.
   78: (See
   79: .Xr mount 2
   80: and
   81: .Xr mount 8 . )
   82: .Pp
   83: The directory entry format is defined in the file
   84: .Aq sys/dirent.h
   85: (which should not be included directly by applications):
   86: .Bd -literal
   87: #ifndef	_SYS_DIRENT_H_
   88: #define	_SYS_DIRENT_H_
   89: 
   90: #include <machine/ansi.h>
   91: 
   92: /*
   93:  * The dirent structure defines the format of directory entries returned by
   94:  * the getdirentries(2) system call.
   95:  *
   96:  * A directory entry has a struct dirent at the front of it, containing its
   97:  * inode number, the length of the entry, and the length of the name
   98:  * contained in the entry.  These are followed by the name padded to a 4
   99:  * byte boundary with null bytes.  All names are guaranteed null terminated.
  100:  * The maximum length of a name in a directory is MAXNAMLEN.
  101:  */
  102: 
  103: struct dirent {
  104: 	__uint32_t d_fileno;		/* file number of entry */
  105: 	__uint16_t d_reclen;		/* length of this record */
  106: 	__uint8_t  d_type; 		/* file type, see below */
  107: 	__uint8_t  d_namlen;		/* length of string in d_name */
  108: #ifdef _POSIX_SOURCE
  109: 	char	d_name[255 + 1];	/* name must be no longer than this */
  110: #else
  111: #define	MAXNAMLEN	255
  112: 	char	d_name[MAXNAMLEN + 1];	/* name must be no longer than this */
  113: #endif
  114: };
  115: 
  116: /*
  117:  * File types
  118:  */
  119: #define	DT_UNKNOWN	 0
  120: #define	DT_FIFO		 1
  121: #define	DT_CHR		 2
  122: #define	DT_DIR		 4
  123: #define	DT_BLK		 6
  124: #define	DT_REG		 8
  125: #define	DT_LNK		10
  126: #define	DT_SOCK		12
  127: #define	DT_WHT		14
  128: 
  129: /*
  130:  * Convert between stat structure types and directory types.
  131:  */
  132: #define	IFTODT(mode)	(((mode) & 0170000) >> 12)
  133: #define	DTTOIF(dirtype)	((dirtype) << 12)
  134: 
  135: /*
  136:  * The _GENERIC_DIRSIZ macro gives the minimum record length which will hold
  137:  * the directory entry.  This requires the amount of space in struct direct
  138:  * without the d_name field, plus enough space for the name with a terminating
  139:  * null byte (dp->d_namlen+1), rounded up to a 4 byte boundary.
  140:  */
  141: #define	_GENERIC_DIRSIZ(dp) \
  142:     ((sizeof (struct dirent) - (MAXNAMLEN+1)) + (((dp)->d_namlen+1 + 3) &~ 3))
  143: 
  144: #ifdef _KERNEL
  145: #define	GENERIC_DIRSIZ(dp)	_GENERIC_DIRSIZ(dp)
  146: #endif
  147: 
  148: #endif /* !_SYS_DIRENT_H_ */
  149: .Ed
  150: .Sh SEE ALSO
  151: .Xr fs 5 ,
  152: .Xr inode 5
  153: .Sh BUGS
  154: The usage of the member d_type of struct dirent is unportable as it is
  155: .Fx Ns -specific .
  156: It also may fail on certain filesystems, for example the cd9660 filesystem.
  157: .Sh HISTORY
  158: A
  159: .Nm
  160: file format appeared in
  161: .At v7 .