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