1 .\" $NetBSD: 2.2.t,v 1.3 1999/02/12 15:04:01 kleink Exp $
3 .\" Copyright (c) 1983, 1993, 1994
4 .\" The Regents of the University of California. All rights reserved.
6 .\" Redistribution and use in source and binary forms, with or without
7 .\" modification, are permitted provided that the following conditions
9 .\" 1. Redistributions of source code must retain the above copyright
10 .\" notice, this list of conditions and the following disclaimer.
11 .\" 2. Redistributions in binary form must reproduce the above copyright
12 .\" notice, this list of conditions and the following disclaimer in the
13 .\" documentation and/or other materials provided with the distribution.
14 .\" 3. Neither the name of the University nor the names of its contributors
15 .\" may be used to endorse or promote products derived from this software
16 .\" without specific prior written permission.
18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
21 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
30 .\" @(#)2.2.t 8.8 (Berkeley) 6/1/94
36 The filesystem abstraction provides access to a hierarchical
38 The filesystem contains directories (each of which may contain
39 sub-directories) as well as files and references to other
40 objects such as devices and inter-process communications sockets.
42 Each file is organized as a linear array of bytes. No record
43 boundaries or system related information is present in
45 Files may be read and written in a random-access fashion.
46 If permitted by the underlying storage mechanism,
47 the user may read the data in a directory as though
48 it were an ordinary file to determine the names of the contained files,
49 but only the system may write into the directories.
52 The filesystem calls take \fIpath name\fP arguments.
53 These consist of a zero or more component \fIfile names\fP
54 separated by ``/\^'' characters, where each file name
55 is up to NAME_MAX (255) characters excluding null and ``/\^''.
56 Each pathname is up to PATH_MAX (1024) characters excluding null.
58 Each process always has two naming contexts: one for the
59 root directory of the filesystem and one for the
60 current working directory. These are used
61 by the system in the filename translation process.
62 If a path name begins with a ``/\^'', it is called
63 a full path name and interpreted relative to the root directory context.
64 If the path name does not begin with a ``/\^'' it is called
65 a relative path name and interpreted relative to the current directory
68 The file name ``.'' in each directory refers to that directory.
69 The file name ``..'' in each directory refers to
70 the parent directory of that directory.
71 The parent directory of the root of the filesystem is itself.
75 .Fd chdir 1 "change current working directory
80 .Fd fchdir 1 "change current working directory
85 .Fd chroot 1 "change root directory
89 change the current working directory or root directory context of a process.
90 Only the super-user can change the root directory context of a process.
92 Information about a filesystem that contains a particular
93 file can be obtained using the calls:
95 .Fd statfs 2 "get file system statistics
97 char *path; struct statfs *buf;
100 .Fd fstatfs 2 "get file system statistics
102 int fd; struct statfs *buf;
104 .Sh 3 "Creation and removal
106 The filesystem allows directories, files, special devices,
107 and fifos to be created and removed from the filesystem.
108 .Sh 4 "Directory creation and removal
110 A directory is created with the
114 .Fd mkdir 2 "make a directory file
116 char *path; mode_t mode;
118 where the mode is defined as for files (see section
120 Directories are removed with the
124 .Fd rmdir 1 "remove a directory file
128 A directory must be empty (other than the entries ``.'' and ``..'')
129 if it is to be deleted.
131 Although directories can be read as files,
132 the usual interface is to use the call:
134 .Fd getdirentries 4 "get directory entries in a filesystem independent format
135 getdirentries(fd, buf, nbytes, basep);
136 int fd; char *buf; int nbytes; long *basep;
140 system call returns a canonical array of directory entries
141 in the filesystem independent format described in \fI<dirent.h>\fP.
142 Application programs usually use the library routines
147 which provide a more convenient interface than
149 The \fIfts\fP package is provided
150 for recursive directory traversal.
153 Files are opened and/or created with the
157 .Fd open 3 "open or create a file for reading or writing
158 fd = open(path, oflag, mode);
159 result int fd; char *path; int oflag; mode_t mode;
161 The \fIpath\fP parameter specifies the name of the
163 The \fIoflag\fP parameter must
164 include O_CREAT to cause the file to be created.
165 Bits for \fIoflag\fP are
166 defined in \fI<fcntl.h>\fP:
170 O_RDONLY /* open for reading only */
171 O_WRONLY /* open for writing only */
172 O_RDWR /* open for reading and writing */
173 O_NONBLOCK /* no delay */
174 O_APPEND /* set append mode */
175 O_SHLOCK /* open with shared file lock */
176 O_EXLOCK /* open with exclusive file lock */
177 O_ASYNC /* signal pgrp when data ready */
178 O_FSYNC /* synchronous writes */
179 O_CREAT /* create if nonexistent */
180 O_TRUNC /* truncate to zero length */
181 O_EXCL /* error if already exists */
185 One of O_RDONLY, O_WRONLY and O_RDWR should be specified,
186 indicating what types of operations are desired to be done
187 on the open file. The operations will be checked against the user's
188 access rights to the file before allowing the
191 Specifying O_APPEND causes all writes to be appended to the file.
192 Specifying O_TRUNC causes the file to be truncated when opened.
193 The flag O_CREAT causes the file to be created if it does not exist,
194 owned by the current user and the group of the containing directory.
195 The permissions for the new file are specified in \fImode\fP
196 as the OR of the appropriate permissions as defined in \fI<sys/stat.h>\fP:
200 S_IRWXU /* RWX for owner */
201 S_IRUSR /* R for owner */
202 S_IWUSR /* W for owner */
203 S_IXUSR /* X for owner */
204 S_IRWXG /* RWX for group */
205 S_IRGRP /* R for group */
206 S_IWGRP /* W for group */
207 S_IXGRP /* X for group */
208 S_IRWXO /* RWX for other */
209 S_IROTH /* R for other */
210 S_IWOTH /* W for other */
211 S_IXOTH /* X for other */
212 S_ISUID /* set user id */
213 S_ISGID /* set group id */
214 S_ISTXT /* sticky bit */
218 Historically, the file mode has been used as a four digit octal number.
219 The bottom three digits encode read access as 4, write access as 2 and
220 execute access as 1, or'ed together.
221 The 0700 bits describe owner access, the 070 bits describe the access
222 rights for processes in the same group as the file, and the 07 bits
223 describe the access rights for other processes.
224 The 7000 bits encode set user ID as 4000, set group ID as 2000, and the
226 The mode specified to
229 the process \fIumask\fP; permissions specified in the
230 \fIumask\fP are cleared in the mode of the created file.
231 The \fIumask\fP can be changed with the call:
233 .Fd umask 1 "set file creation mode mask
234 oldmask = umask(newmask);
235 result mode_t oldmask; mode_t newmask;
238 If the O_EXCL flag is set, and the file already exists, then the
240 will fail without affecting the file in any way.
241 This mechanism provides a simple exclusive access facility.
242 For security reasons,
243 if the O_EXCL flag is set and the file is a symbolic link,
244 the open will fail regardless of the existence of the file
245 referenced by the link.
246 The O_SHLOCK and O_EXLOCK flags allow the file to be atomically
255 The O_ASYNC flag enables the SIGIO signal to be sent to
256 the process group of the opening process when I/O is possible,
257 e.g., upon availability of data to be read.
258 .Sh 4 "Creating references to devices
260 The filesystem allows entries which reference peripheral devices.
261 Peripherals are distinguished as \fIblock\fP or \fIcharacter\fP
262 devices according by their ability to support block-oriented
264 Devices are identified by their ``major'' and ``minor''
265 device numbers. The major device number determines the kind
266 of peripheral it is, while the minor device number indicates
267 either one of possibly many peripherals of that kind, or special
268 characteristics of the peripheral.
269 Structured devices have all operations done internally
270 in ``block'' quantities while unstructured devices
271 may have input and output done in varying units, and
272 may act as a non-seekable communications channel rather than a random-access
276 call creates special entries:
278 .Fd mknod 3 "make a special file node
279 mknod(path, mode, dev);
280 char *path; mode_t mode; dev_t dev;
282 where \fImode\fP is formed from the object type
283 and access permissions. The parameter \fIdev\fP is a configuration
284 dependent parameter used to identify specific character or
287 Fifo's can be created in the filesystem using the call:
289 .Fd mkfifo 2 "make a fifo file
291 char *path; mode_t mode;
293 The \fImode\fP parameter is used solely to specify the access
294 permissions of the newly created fifo.
295 .Sh 4 "Links and renaming
297 Links allow multiple names for a file to exist.
298 Links exist independently of the file to which they are linked.
300 Two types of links exist, \fIhard\fP links and \fIsymbolic\fP
301 links. A hard link is a reference counting mechanism that
302 allows a file to have multiple names within the same filesystem.
303 Each link to a file is equivalent, referring to the file independently
305 Symbolic links cause string substitution
306 during the pathname interpretation process, and refer to a file name
307 rather than referring directly to a file.
309 Hard links and symbolic links have different
310 properties. A hard link ensures that the target
311 file will always be accessible, even after its original
312 directory entry is removed; no such guarantee exists for a symbolic link.
314 symbolic links can refernce directories and span filesystems boundaries.
319 call on a hard link will return the information about the
320 file (or directory) that the link references while an
322 call on a symbolic link will return information about the link itself.
323 A symbolic link does not have an owner,
324 group, permissions, access and modification times, etc.
325 The only attributes returned from an
327 that refer to the symbolic link itself
328 are the file type (S_IFLNK), size, blocks, and link count (always 1).
329 The other attributes are filled in from
330 the directory that contains the link.
332 The following calls create a new link, named \fIpath2\fP,
335 .Fd link 2 "make a hard file link
340 .Fd symlink 2 "make a symbolic link to a file
341 symlink(path1, path2);
346 primitive may be used to remove
349 If a file is a symbolic link, the ``value'' of the
350 link may be read with the
354 .Fd readlink 3 "read value of a symbolic link
355 len = readlink(path, buf, bufsize);
356 result int len; char *path; result char *buf; int bufsize;
358 This call returns, in \fIbuf\fP, the string substituted into
359 pathnames passing through \fIpath\fP\|.
360 (This string is not NULL terminated.)
362 Atomic renaming of filesystem resident objects is possible with the
366 .Fd rename 2 "change the name of a file
367 rename(oldname, newname);
368 char *oldname, *newname;
370 where both \fIoldname\fP and \fInewname\fP must be
371 in the same filesystem.
372 If either \fIoldname\fP or \fInewname\fP is a directory,
373 then the other also must be a directory for the
376 If \fInewname\fP exists and is a directory, then it must be empty.
377 .Sh 4 "File, device, and fifo removal
379 A reference to a file, special device or fifo may be removed with the
383 .Fd unlink 1 "remove directory entry
387 The caller must have write access to the directory in which
388 the file is located for this call to be successful.
389 When the last name for a file has been removed, the file may no longer
390 be opened; the file itself is removed once any existing references
393 All current access to a file can be revoked using the call:
395 .Fd revoke 1 "revoke file access
399 Subsequent operations on any descriptors open at the time of the
401 fail, with the exceptions that a
403 call will succeed, and a
405 from a character device file which has been revoked returns a count
406 of zero (end of file).
407 If the file is a special file for a device which is open,
408 the device close function is called as if all open references
409 to the file had been closed.
414 This call is most useful for revoking access to a terminal line after
415 a hangup in preparation for reuse by a new login session.
416 Access to a controlling terminal is automatically revoked
417 when the session leader for the session exits.
418 .Sh 3 "Reading and modifying file attributes
420 Detailed information about the attributes of a file
421 may be obtained with the calls:
423 .Fd stat 2 "get file status
425 char *path; result struct stat *stb;
428 .Fd fstat 2 "get file status
430 int fd; result struct stat *stb;
432 The \fIstat\fP structure includes the file
433 type, protection, ownership, access times,
434 size, and a count of hard links.
435 If the file is a symbolic link, then the status of the link
436 itself (rather than the file the link references)
437 may be obtained using the
441 .Fd lstat 2 "get file status
443 char *path; result struct stat *stb;
446 Newly created files are assigned the user ID of the process that created
447 them and the group ID of the directory in which they were created.
448 The ownership of a file may be changed by either of the calls:
450 .Fd chown 3 "change owner and group of a file
451 chown(path, owner, group);
452 char *path; uid_t owner; gid_t group;
455 .Fd fchown 3 "change owner and group of a file
456 fchown(fd, owner, group);
457 int fd, uid_t owner; gid_t group;
460 In addition to ownership, each file has three levels of access
461 protection associated with it. These levels are owner relative,
462 group relative, and other.
463 Each level of access has separate indicators for read permission,
464 write permission, and execute permission.
465 The protection bits associated with a file may be set by either
468 .Fd chmod 2 "change mode of file
470 char *path; mode_t mode;
473 .Fd fchmod 2 "change mode of file
477 where \fImode\fP is a value indicating the new protection
478 of the file, as listed in section
481 Each file has a set of flags stored as a bit mask associated with it.
482 These flags are returned in the \fIstat\fP structure and
483 are set using the calls:
485 .Fd chflags 2 "set file flags
486 chflags(path, flags);
487 char *path; u_long flags;
490 .Fd fchflags 2 "set file flags
492 int fd; u_long flags;
495 The flags specified are formed by or'ing the following values:
499 UF_NODUMP Do not dump the file.
500 UF_IMMUTABLE The file may not be changed.
501 UF_APPEND The file may only be appended to.
502 SF_IMMUTABLE The file may not be changed.
503 SF_APPEND The file may only be appended to.
506 The UF_NODUMP, UF_IMMUTABLE and UF_APPEND
507 flags may be set or unset by either the owner of a file or the super-user.
508 The SF_IMMUTABLE and SF_APPEND
509 flags may only be set or unset by the super-user.
510 They may be set at any time, but normally may only be unset when
511 the system is in single-user mode.
513 Finally, the access and modify times on a file may be set by the call:
515 .Fd utimes 2 "set file access and modification times
517 char *path; struct timeval *tvp[2];
519 This is particularly useful when moving files between media,
520 to preserve file access and modification times.
521 .Sh 3 "Checking accessibility
523 A process running with
524 different real and effective user-ids
525 may interrogate the accessibility of a file to the
526 real user by using the
530 .Fd access 2 "check access permissions of a file or pathname
531 accessible = access(path, how);
532 result int accessible; char *path; int how;
534 \fIHow\fP is constructed by OR'ing the following bits, defined
539 F_OK /* file exists */
540 X_OK /* file is executable/searchable */
541 W_OK /* file is writable */
542 R_OK /* file is readable */
545 The presence or absence of advisory locks does not affect the
553 functions provide a method for applications to determine the current
554 value of a configurable system limit or option variable associated
555 with a pathname or file descriptor:
557 .Fd pathconf 2 "get configurable pathname variables
558 ans = pathconf(path, name);
559 result long ans; char *path; int name;
562 .Fd fpathconf 2 "get configurable pathname variables
563 ans = fpathconf(fd, name);
564 result long ans; int fd, name;
568 the \fIpath\fP argument is the name of a file or directory.
571 the \fIfd\fP argument is an open file descriptor.
572 The \fIname\fP argument specifies the system variable to be queried.
573 Symbolic constants for each name value are found in the include file
575 .Sh 3 "Extension and truncation
577 Files are created with zero length and may be extended
578 simply by writing or appending to them. While a file is
579 open the system maintains a pointer into the file
580 indicating the current location in the file associated with
581 the descriptor. This pointer may be moved about in the
582 file in a random access fashion.
583 To set the current offset into a file, the
587 .Fd lseek 3 "reposition read/write file offset
588 oldoffset = lseek(fd, offset, type);
589 result off_t oldoffset; int fd; off_t offset; int type;
592 where \fItype\fP is defined by \fI<unistd.h>\fP as one of:
596 SEEK_SET /* set file offset to offset */
597 SEEK_CUR /* set file offset to current plus offset */
598 SEEK_END /* set file offset to EOF plus offset */
601 The call ``lseek(fd, 0, SEEK_CUR)''
602 returns the current offset into the file.
604 Files may have ``holes'' in them.
605 Holes are areas in the linear extent of the file where data has never
607 These may be created by seeking to a location in a file past the
608 current end-of-file and writing.
609 Holes are treated by the system as zero valued bytes.
611 A file may be extended or truncated with either of the calls:
613 .Fd truncate 2 "truncate a file to a specified length
614 truncate(path, length);
615 char *path; off_t length;
618 .Fd ftruncate 2 "truncate a file to a specified length
619 ftruncate(fd, length);
620 int fd; off_t length;
622 changing the size of the specified file to \fIlength\fP bytes.
624 Unless opened with the O_FSYNC flag,
625 writes to files are held for an indeterminate period of time
626 in the system buffer cache.
629 .Fd fsync 1 "synchronize in-core state of a file with that on disk
633 ensures that the contents of a file are committed to disk
635 This feature is used by applications such as editors that
636 want to ensure the integrity of a new file before continuing.
639 The filesystem provides basic facilities that allow cooperating processes
640 to synchronize their access to shared files. A process may
641 place an advisory \fIread\fP or \fIwrite\fP lock on a file,
642 so that other cooperating processes may avoid interfering
643 with the process' access. This simple mechanism
644 provides locking with file granularity.
645 Byte range locking is available with
649 The system does not force processes to obey the locks;
650 they are of an advisory nature only.
652 Locking can be done as part of the
662 .Fd flock 2 "apply or remove an advisory lock on an open file
666 where the \fIhow\fP parameter is formed from bits
667 defined in \fI<fcntl.h>\fP:
671 LOCK_SH /* shared file lock */
672 LOCK_EX /* exclusive file lock */
673 LOCK_NB /* don't block when locking */
674 LOCK_UN /* unlock file */
677 Successive lock calls may be used to increase or
678 decrease the level of locking. If an object is currently
679 locked by another process when a
681 call is made, the caller will be blocked until the current lock owner
682 releases the lock; this may be avoided by including LOCK_NB
683 in the \fIhow\fP parameter.
684 Specifying LOCK_UN removes all locks associated with the descriptor.
685 Advisory locks held by a process are automatically deleted when
686 the process terminates.
689 As an optional facility, each local filesystem can impose limits on a
690 user's or group's disk usage.
691 Two quantities are limited: the total amount of disk space which
692 a user or group may allocate in a filesystem and the total number of files
693 a user or group may create in a filesystem. Quotas are expressed as
694 \fIhard\fP limits and \fIsoft\fP limits. A hard limit is
695 always imposed; if a user or group would exceed a hard limit, the operation
696 which caused the resource request will fail. A soft limit results
697 in the user or group receiving a warning message,
698 but with allocation succeeding.
699 Facilities are provided to turn soft limits into hard limits if a
700 user or group has exceeded a soft limit for an unreasonable period of time.
704 call enables, disables and manipulates filesystem quotas:
706 .Fd quotactl 4 "manipulate filesystem quotas
707 quotactl(path, cmd, id, addr);
708 char *path; int cmd; int id; char *addr;
710 A quota control command given by cmd operates on the given filename path
711 for the given user ID. The address of an optional command specific data
712 structure, addr, may be given.
713 The supported commands include:
717 Q_QUOTAON /* enable quotas */
718 Q_QUOTAOFF /* disable quotas */
719 Q_GETQUOTA /* get limits and usage */
720 Q_SETQUOTA /* set limits and usage */
721 Q_SETUSE /* set usage */
722 Q_SYNC /* sync disk copy of a filesystems quotas */
725 .Sh 3 "Remote filesystems
727 There are two system calls intended to help support the remote filesystem
731 .Fd nfssvc 2 "NFS services
732 nfssvc(flags, argstructp);
733 int flags, void *argstructp;
735 is used by the NFS daemons to pass information into
736 and out of the kernel and also to enter the kernel as a server daemon.
737 The flags argument consists of several bits that show what action is to
738 be taken once in the kernel and \fIargstructp\fP points to one of three
739 structures depending on which bits are set in flags.
743 .Fd getfh 2 "get file handle
745 char *path; result fhandle_t *fhp;
747 returns a file handle for the specified file or directory in the
748 file handle pointed to by fhp.
749 This file handle can then be used in future calls to NFS to access
750 the file without the need to repeat the pathname translation.
751 This system call is restricted to the superuser.
752 .Sh 3 "Other filesystems
754 The kernel supports many other filesystems.
757 The log-structured filesystem. It provides an alternate disk
758 layout than the fast filesystem optimized for writing rather
760 For further information see the
764 .\" We currently do not document the LFS calls
767 .\" .Fd lfs_segclean 2
768 .\" .Fd lfs_segwait 2
770 The ISO-standard 9660 filesystem with Rock Ridge extensions used for CD-ROMs.
771 For further information see the
775 The file descriptor mapping filesystem.
776 For further information see the
780 The /proc filesystem as an alternative for debuggers.
781 For further information see section
787 The memory-based filesystem,
788 used primarily for fast but ethereal uses such as /tmp.
789 For further information see the
793 The kernel variable filesystem, used as an alternative to
795 For further information see section
801 The portal filesystem, used to mount processes in the filesystem.
802 For further information see the
806 The uid/gid remapping filesystem, usually layered above NFS filesystems
807 exported to an outside administrative domain.
808 For further information see the
812 The union filesystem, used to place a writable filesystem above
813 a read-only filesystem.
814 This filesystem is useful for compiling sources on a CD-ROM
815 without having to copy the CD-ROM contents to writable disk.
816 For further information see the