/share/doc/psd/05.sysman/2.2.t

  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 2.2.3.2.
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[2];
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.