Return to 2.2.t CVS log

Up to [CSRG BSD Unix] / 43BSDReno / share / doc / ps1 / 06.sysman

Annotation of 43BSDReno/share/doc/ps1/06.sysman/2.2.t, revision 1.1

1.1     ! root        1: .\" Copyright (c) 1983 Regents of the University of California.
        !             2: .\" All rights reserved.  The Berkeley software License Agreement
        !             3: .\" specifies the terms and conditions for redistribution.
        !             4: .\"
        !             5: .\"    @(#)2.2.t       6.3 (Berkeley) 5/12/86
        !             6: .\"
        !             7: .sh "File system
        !             8: .NH 3
        !             9: Overview
        !            10: .PP
        !            11: The file system abstraction provides access to a hierarchical
        !            12: file system structure.
        !            13: The file system contains directories (each of which may contain
        !            14: other sub-directories) as well as files and references to other
        !            15: objects such as devices and inter-process communications sockets.
        !            16: .PP
        !            17: Each file is organized as a linear array of bytes.  No record
        !            18: boundaries or system related information is present in
        !            19: a file.
        !            20: Files may be read and written in a random-access fashion.
        !            21: The user may read the data in a directory as though
        !            22: it were an ordinary file to determine the names of the contained files,
        !            23: but only the system may write into the directories.
        !            24: The file system stores only a small amount of ownership, protection and usage
        !            25: information with a file.
        !            26: .NH 3
        !            27: Naming
        !            28: .PP
        !            29: The file system calls take \fIpath name\fP arguments.
        !            30: These consist of a zero or more component \fIfile names\fP
        !            31: separated by ``/\^'' characters, where each file name
        !            32: is up to 255 ASCII characters excluding null and ``/\^''.
        !            33: .PP
        !            34: Each process always has two naming contexts: one for the
        !            35: root directory of the file system and one for the
        !            36: current working directory.  These are used
        !            37: by the system in the filename translation process.
        !            38: If a path name begins with a ``/\^'', it is called
        !            39: a full path name and interpreted relative to the root directory context.
        !            40: If the path name does not begin with a ``/\^'' it is called
        !            41: a relative path name and interpreted relative to the current directory
        !            42: context.
        !            43: .PP
        !            44: The system limits
        !            45: the total length of a path name to 1024 characters.
        !            46: .PP
        !            47: The file name ``..'' in each directory refers to
        !            48: the parent directory of that directory.
        !            49: The parent directory of the root of the file system is always that directory.
        !            50: .PP
        !            51: The calls
        !            52: .DS
        !            53: chdir(path);
        !            54: char *path;
        !            55: 
        !            56: chroot(path)
        !            57: char *path;
        !            58: .DE
        !            59: change the current working directory and root directory context of a process.
        !            60: Only the super-user can change the root directory context of a process.
        !            61: .NH 3
        !            62: Creation and removal
        !            63: .PP
        !            64: The file system allows directories, files, special devices,
        !            65: and ``portals'' to be created and removed from the file system.
        !            66: .NH 4
        !            67: Directory creation and removal
        !            68: .PP
        !            69: A directory is created with the \fImkdir\fP system call:
        !            70: .DS
        !            71: mkdir(path, mode);
        !            72: char *path; int mode;
        !            73: .DE
        !            74: where the mode is defined as for files (see below).
        !            75: Directories are removed with the \fIrmdir\fP system call:
        !            76: .DS
        !            77: rmdir(path);
        !            78: char *path;
        !            79: .DE
        !            80: A directory must be empty if it is to be deleted.
        !            81: .NH 4
        !            82: File creation
        !            83: .PP
        !            84: Files are created with the \fIopen\fP system call,
        !            85: .DS
        !            86: fd = open(path, oflag, mode);
        !            87: result int fd; char *path; int oflag, mode;
        !            88: .DE
        !            89: The \fIpath\fP parameter specifies the name of the
        !            90: file to be created.  The \fIoflag\fP parameter must
        !            91: include O_CREAT from below to cause the file to be created.
        !            92: Bits for \fIoflag\fP are
        !            93: defined in \fI<sys/file.h>\fP:
        !            94: .DS
        !            95: ._d
        !            96: #define        O_RDONLY        000     /* open for reading */
        !            97: #define        O_WRONLY        001     /* open for writing */
        !            98: #define        O_RDWR  002     /* open for read & write */
        !            99: #define        O_NDELAY        004     /* non-blocking open */
        !           100: #define        O_APPEND        010     /* append on each write */
        !           101: #define        O_CREAT 01000   /* open with file create */
        !           102: #define        O_TRUNC 02000   /* open with truncation */
        !           103: #define        O_EXCL  04000   /* error on create if file exists */
        !           104: .DE
        !           105: .PP
        !           106: One of O_RDONLY, O_WRONLY and O_RDWR should be specified,
        !           107: indicating what types of operations are desired to be performed
        !           108: on the open file.  The operations will be checked against the user's
        !           109: access rights to the file before allowing the \fIopen\fP to succeed.
        !           110: Specifying O_APPEND causes writes to automatically append to the
        !           111: file.
        !           112: The flag O_CREAT causes the file to be created if it does not
        !           113: exist, owned by the current user
        !           114: and the group of the containing directory.
        !           115: The protection for the new file is specified in \fImode\fP.
        !           116: The file mode is used as a three digit octal number.
        !           117: Each digit encodes read access as 4, write access as 2 and execute
        !           118: access as 1, or'ed together.  The 0700 bits describe owner
        !           119: access, the 070 bits describe the access rights for processes in the same
        !           120: group as the file, and the 07 bits describe the access rights
        !           121: for other processes.
        !           122: .PP
        !           123: If the open specifies to create the file with O_EXCL
        !           124: and the file already exists, then the \fIopen\fP will fail
        !           125: without affecting the file in any way.  This provides a
        !           126: simple exclusive access facility.
        !           127: If the file exists but is a symbolic link, the open will fail
        !           128: regardless of the existence of the file specified by the link.
        !           129: .NH 4
        !           130: Creating references to devices
        !           131: .PP
        !           132: The file system allows entries which reference peripheral devices.
        !           133: Peripherals are distinguished as \fIblock\fP or \fIcharacter\fP
        !           134: devices according by their ability to support block-oriented
        !           135: operations.
        !           136: Devices are identified by their ``major'' and ``minor''
        !           137: device numbers.  The major device number determines the kind
        !           138: of peripheral it is, while the minor device number indicates
        !           139: one of possibly many peripherals of that kind.
        !           140: Structured devices have all operations performed internally
        !           141: in ``block'' quantities while
        !           142: unstructured devices often have a number of
        !           143: special \fIioctl\fP operations, and may have input and output
        !           144: performed in varying units.
        !           145: The \fImknod\fP call creates special entries:
        !           146: .DS
        !           147: mknod(path, mode, dev);
        !           148: char *path; int mode, dev;
        !           149: .DE
        !           150: where \fImode\fP is formed from the object type
        !           151: and access permissions.  The parameter \fIdev\fP is a configuration
        !           152: dependent parameter used to identify specific character or
        !           153: block I/O devices.
        !           154: .NH 4
        !           155: Portal creation\(dg
        !           156: .PP
        !           157: .FS
        !           158: \(dg The \fIportal\fP call is not implemented in 4.3BSD.
        !           159: .FE
        !           160: The call
        !           161: .DS
        !           162: fd = portal(name, server, param, dtype, protocol, domain, socktype)
        !           163: result int fd; char *name, *server, *param; int dtype, protocol;
        !           164: int domain, socktype;
        !           165: .DE
        !           166: places a \fIname\fP in the file system name space that causes connection to a
        !           167: server process when the name is used.
        !           168: The portal call returns an active portal in \fIfd\fP as though an
        !           169: access had occurred to activate an inactive portal, as now described.
        !           170: .PP
        !           171: When an inactive portal is accessed, the system sets up a socket
        !           172: of the specified \fIsocktype\fP in the specified communications
        !           173: \fIdomain\fP (see section 2.3), and creates the \fIserver\fP process,
        !           174: giving it the specified \fIparam\fP as argument to help it identify
        !           175: the portal, and also giving it the newly created socket as descriptor
        !           176: number 0.  The accessor of the portal will create a socket in the same
        !           177: \fIdomain\fP and \fIconnect\fP to the server.  The user will then
        !           178: \fIwrap\fP the socket in the specified \fIprotocol\fP to create an object of
        !           179: the required descriptor type \fIdtype\fP and proceed with the
        !           180: operation which was in progress before the portal was encountered.
        !           181: .PP
        !           182: While the server process holds the socket (which it received as \fIfd\fP
        !           183: from the \fIportal\fP call on descriptor 0 at activation) further references
        !           184: will result in connections being made to the same socket.
        !           185: .NH 4
        !           186: File, device, and portal removal
        !           187: .PP
        !           188: A reference to a file, special device or portal may be removed with the
        !           189: \fIunlink\fP call,
        !           190: .DS
        !           191: unlink(path);
        !           192: char *path;
        !           193: .DE
        !           194: The caller must have write access to the directory in which
        !           195: the file is located for this call to be successful.
        !           196: .NH 3
        !           197: Reading and modifying file attributes
        !           198: .PP
        !           199: Detailed information about the attributes of a file
        !           200: may be obtained with the calls:
        !           201: .DS
        !           202: #include <sys/stat.h>
        !           203: 
        !           204: stat(path, stb);
        !           205: char *path; result struct stat *stb;
        !           206: 
        !           207: fstat(fd, stb);
        !           208: int fd; result struct stat *stb;
        !           209: .DE
        !           210: The \fIstat\fP structure includes the file
        !           211: type, protection, ownership, access times,
        !           212: size, and a count of hard links.
        !           213: If the file is a symbolic link, then the status of the link
        !           214: itself (rather than the file the link references)
        !           215: may be found using the \fIlstat\fP call:
        !           216: .DS
        !           217: lstat(path, stb);
        !           218: char *path; result struct stat *stb;
        !           219: .DE
        !           220: .PP
        !           221: Newly created files are assigned the user id of the
        !           222: process that created it and the group id of the directory
        !           223: in which it was created.  The ownership of a file may
        !           224: be changed by either of the calls
        !           225: .DS
        !           226: chown(path, owner, group);
        !           227: char *path; int owner, group;
        !           228: 
        !           229: fchown(fd, owner, group);
        !           230: int fd, owner, group;
        !           231: .DE
        !           232: .PP
        !           233: In addition to ownership, each file has three levels of access
        !           234: protection associated with it.  These levels are owner relative,
        !           235: group relative, and global (all users and groups).  Each level
        !           236: of access has separate indicators for read permission, write
        !           237: permission, and execute permission.
        !           238: The protection bits associated with a file may be set by either
        !           239: of the calls:
        !           240: .DS
        !           241: chmod(path, mode);
        !           242: char *path; int mode;
        !           243: 
        !           244: fchmod(fd, mode);
        !           245: int fd, mode;
        !           246: .DE
        !           247: where \fImode\fP is a value indicating the new protection
        !           248: of the file, as listed in section 2.2.3.2.
        !           249: .PP
        !           250: Finally, the access and modify times on a file may be set by the call:
        !           251: .DS
        !           252: utimes(path, tvp)
        !           253: char *path; struct timeval *tvp[2];
        !           254: .DE
        !           255: This is particularly useful when moving files between media, to
        !           256: preserve relationships between the times the file was modified.
        !           257: .NH 3
        !           258: Links and renaming
        !           259: .PP
        !           260: Links allow multiple names for a file
        !           261: to exist.  Links exist independently of the file linked to.
        !           262: .PP
        !           263: Two types of links exist, \fIhard\fP links and \fIsymbolic\fP
        !           264: links.  A hard link is a reference counting mechanism that
        !           265: allows a file to have multiple names within the same file
        !           266: system.  Symbolic links cause string substitution
        !           267: during the pathname interpretation process.
        !           268: .PP
        !           269: Hard links and symbolic links have different
        !           270: properties.  A hard link insures the target
        !           271: file will always be accessible, even after its original
        !           272: directory entry is removed; no such guarantee exists for a symbolic link.
        !           273: Symbolic links can span file systems boundaries.
        !           274: .PP
        !           275: The following calls create a new link, named \fIpath2\fP,
        !           276: to \fIpath1\fP:
        !           277: .DS
        !           278: link(path1, path2);
        !           279: char *path1, *path2;
        !           280: 
        !           281: symlink(path1, path2);
        !           282: char *path1, *path2;
        !           283: .DE
        !           284: The \fIunlink\fP primitive may be used to remove
        !           285: either type of link. 
        !           286: .PP
        !           287: If a file is a symbolic link, the ``value'' of the
        !           288: link may be read with the \fIreadlink\fP call,
        !           289: .DS
        !           290: len = readlink(path, buf, bufsize);
        !           291: result int len; result char *path, *buf; int bufsize;
        !           292: .DE
        !           293: This call returns, in \fIbuf\fP, the null-terminated string
        !           294: substituted into pathnames passing through \fIpath\fP\|.
        !           295: .PP
        !           296: Atomic renaming of file system resident objects is possible
        !           297: with the \fIrename\fP call:
        !           298: .DS
        !           299: rename(oldname, newname);
        !           300: char *oldname, *newname;
        !           301: .DE
        !           302: where both \fIoldname\fP and \fInewname\fP must be
        !           303: in the same file system.
        !           304: If \fInewname\fP exists and is a directory, then it must be empty.
        !           305: .NH 3
        !           306: Extension and truncation
        !           307: .PP
        !           308: Files are created with zero length and may be extended
        !           309: simply by writing or appending to them.  While a file is
        !           310: open the system maintains a pointer into the file
        !           311: indicating the current location in the file associated with
        !           312: the descriptor.  This pointer may be moved about in the
        !           313: file in a random access fashion.
        !           314: To set the current offset into a file, the \fIlseek\fP
        !           315: call may be used,
        !           316: .DS
        !           317: oldoffset = lseek(fd, offset, type);
        !           318: result off_t oldoffset; int fd; off_t offset; int type;
        !           319: .DE
        !           320: where \fItype\fP is given in \fI<sys/file.h>\fP as one of:
        !           321: .DS
        !           322: ._d
        !           323: #define        L_SET   0       /* set absolute file offset */
        !           324: #define        L_INCR  1       /* set file offset relative to current position */
        !           325: #define        L_XTND  2       /* set offset relative to end-of-file */
        !           326: .DE
        !           327: The call ``lseek(fd, 0, L_INCR)''
        !           328: returns the current offset into the file.
        !           329: .PP
        !           330: Files may have ``holes'' in them.  Holes are void areas in the
        !           331: linear extent of the file where data has never been
        !           332: written.  These may be created by seeking to
        !           333: a location in a file past the current end-of-file and writing.
        !           334: Holes are treated by the system as zero valued bytes.
        !           335: .PP
        !           336: A file may be truncated with either of the calls:
        !           337: .DS
        !           338: truncate(path, length);
        !           339: char *path; int length;
        !           340: 
        !           341: ftruncate(fd, length);
        !           342: int fd, length;
        !           343: .DE
        !           344: reducing the size of the specified file to \fIlength\fP bytes.
        !           345: .NH 3
        !           346: Checking accessibility
        !           347: .PP
        !           348: A process running with
        !           349: different real and effective user ids
        !           350: may interrogate the accessibility of a file to the
        !           351: real user by using
        !           352: the \fIaccess\fP call:
        !           353: .DS
        !           354: accessible = access(path, how);
        !           355: result int accessible; char *path; int how;
        !           356: .DE
        !           357: Here \fIhow\fP is constructed by or'ing the following bits, defined
        !           358: in \fI<sys/file.h>\fP:
        !           359: .DS
        !           360: ._d
        !           361: #define        F_OK    0       /* file exists */
        !           362: #define        X_OK    1       /* file is executable */
        !           363: #define        W_OK    2       /* file is writable */
        !           364: #define        R_OK    4       /* file is readable */
        !           365: .DE
        !           366: The presence or absence of advisory locks does not affect the
        !           367: result of \fIaccess\fP\|.
        !           368: .NH 3
        !           369: Locking
        !           370: .PP
        !           371: The file system provides basic facilities that allow cooperating processes
        !           372: to synchronize their access to shared files.  A process may
        !           373: place an advisory \fIread\fP or \fIwrite\fP lock on a file,
        !           374: so that other cooperating processes may avoid interfering
        !           375: with the process' access.  This simple mechanism
        !           376: provides locking with file granularity.  More granular
        !           377: locking can be built using the IPC facilities to provide a lock
        !           378: manager.
        !           379: The system does not force processes to obey the locks;
        !           380: they are of an advisory nature only.
        !           381: .PP
        !           382: Locking is performed after an \fIopen\fP call by applying the
        !           383: \fIflock\fP primitive,
        !           384: .DS
        !           385: flock(fd, how);
        !           386: int fd, how;
        !           387: .DE
        !           388: where the \fIhow\fP parameter is formed from bits defined in \fI<sys/file.h>\fP:
        !           389: .DS
        !           390: ._d
        !           391: #define        LOCK_SH 1       /* shared lock */
        !           392: #define        LOCK_EX 2       /* exclusive lock */
        !           393: #define        LOCK_NB 4       /* don't block when locking */
        !           394: #define        LOCK_UN 8       /* unlock */
        !           395: .DE
        !           396: Successive lock calls may be used to increase or
        !           397: decrease the level of locking.  If an object is currently
        !           398: locked by another process when a \fIflock\fP call is made,
        !           399: the caller will be blocked until the current lock owner
        !           400: releases the lock; this may be avoided by including LOCK_NB
        !           401: in the \fIhow\fP parameter.
        !           402: Specifying LOCK_UN removes all locks associated with the descriptor.
        !           403: Advisory locks held by a process are automatically deleted when
        !           404: the process terminates.
        !           405: .NH 3
        !           406: Disk quotas
        !           407: .PP
        !           408: As an optional facility, each file system may be requested to
        !           409: impose limits on a user's disk usage.
        !           410: Two quantities are limited: the total amount of disk space which
        !           411: a user may allocate in a file system and the total number of files
        !           412: a user may create in a file system.  Quotas are expressed as
        !           413: \fIhard\fP limits and \fIsoft\fP limits.  A hard limit is
        !           414: always imposed; if a user would exceed a hard limit, the operation
        !           415: which caused the resource request will fail.  A soft limit results
        !           416: in the user receiving a warning message, but with allocation succeeding.
        !           417: Facilities are provided to turn soft limits into hard limits if a
        !           418: user has exceeded a soft limit for an unreasonable period of time.
        !           419: .PP
        !           420: To enable disk quotas on a file system the \fIsetquota\fP call
        !           421: is used:
        !           422: .DS
        !           423: setquota(special, file)
        !           424: char *special, *file;
        !           425: .DE
        !           426: where \fIspecial\fP refers to a structured device file where
        !           427: a mounted file system exists, and
        !           428: \fIfile\fP refers to a disk quota file (residing on the file
        !           429: system associated with \fIspecial\fP) from which user quotas
        !           430: should be obtained.  The format of the disk quota file is 
        !           431: implementation dependent.
        !           432: .PP
        !           433: To manipulate disk quotas the \fIquota\fP call is provided:
        !           434: .DS
        !           435: #include <sys/quota.h>
        !           436: 
        !           437: quota(cmd, uid, arg, addr)
        !           438: int cmd, uid, arg; caddr_t addr;
        !           439: .DE
        !           440: The indicated \fIcmd\fP is applied to the user ID \fIuid\fP.
        !           441: The parameters \fIarg\fP and \fIaddr\fP are command specific.
        !           442: The file \fI<sys/quota.h>\fP contains definitions pertinent to the
        !           443: use of this call.

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.