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

823 lines
26 KiB
Perl
Raw Normal View History

1999-02-12 18:04:00 +03:00
.\" $NetBSD: 2.2.t,v 1.3 1999/02/12 15:04:01 kleink Exp $
1998-01-09 09:54:27 +03:00
.\"
1997-10-17 13:49:00 +04:00
.\" Copyright (c) 1983, 1993, 1994
1994-06-19 04:07:16 +04:00
.\" The Regents of the University of California. All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\" notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\" notice, this list of conditions and the following disclaimer in the
.\" documentation and/or other materials provided with the distribution.
.\" 3. All advertising materials mentioning features or use of this software
.\" must display the following acknowledgement:
.\" This product includes software developed by the University of
.\" California, Berkeley and its contributors.
.\" 4. Neither the name of the University nor the names of its contributors
.\" may be used to endorse or promote products derived from this software
.\" without specific prior written permission.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
1997-10-17 13:49:00 +04:00
.\" @(#)2.2.t 8.8 (Berkeley) 6/1/94
1994-06-19 04:07:16 +04:00
.\"
1997-10-17 13:49:00 +04:00
.ne 1i
.Sh 2 "Filesystem
.Sh 3 "Overview
.PP
The filesystem abstraction provides access to a hierarchical
filesystem structure.
The filesystem contains directories (each of which may contain
sub-directories) as well as files and references to other
1994-06-19 04:07:16 +04:00
objects such as devices and inter-process communications sockets.
.PP
Each file is organized as a linear array of bytes. No record
boundaries or system related information is present in
a file.
Files may be read and written in a random-access fashion.
1997-10-17 13:49:00 +04:00
If permitted by the underlying storage mechanism,
the user may read the data in a directory as though
1994-06-19 04:07:16 +04:00
it were an ordinary file to determine the names of the contained files,
but only the system may write into the directories.
1997-10-17 13:49:00 +04:00
.Sh 3 "Naming
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
The filesystem calls take \fIpath name\fP arguments.
1994-06-19 04:07:16 +04:00
These consist of a zero or more component \fIfile names\fP
separated by ``/\^'' characters, where each file name
1997-10-17 13:49:00 +04:00
is up to NAME_MAX (255) characters excluding null and ``/\^''.
Each pathname is up to PATH_MAX (1024) characters excluding null.
1994-06-19 04:07:16 +04:00
.PP
Each process always has two naming contexts: one for the
1997-10-17 13:49:00 +04:00
root directory of the filesystem and one for the
1994-06-19 04:07:16 +04:00
current working directory. These are used
by the system in the filename translation process.
If a path name begins with a ``/\^'', it is called
a full path name and interpreted relative to the root directory context.
If the path name does not begin with a ``/\^'' it is called
a relative path name and interpreted relative to the current directory
context.
.PP
1997-10-17 13:49:00 +04:00
The file name ``.'' in each directory refers to that directory.
1994-06-19 04:07:16 +04:00
The file name ``..'' in each directory refers to
the parent directory of that directory.
1997-10-17 13:49:00 +04:00
The parent directory of the root of the filesystem is itself.
.LP
The calls:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd chdir 1 "change current working directory
1994-06-19 04:07:16 +04:00
chdir(path);
char *path;
1997-10-17 13:49:00 +04:00
.DE
.DS
.Fd fchdir 1 "change current working directory
fchdir(fd);
int fd;
.DE
.DS
.Fd chroot 1 "change root directory
chroot(path);
1994-06-19 04:07:16 +04:00
char *path;
.DE
1997-10-17 13:49:00 +04:00
change the current working directory or root directory context of a process.
1994-06-19 04:07:16 +04:00
Only the super-user can change the root directory context of a process.
1997-10-17 13:49:00 +04:00
.LP
Information about a filesystem that contains a particular
file can be obtained using the calls:
.DS
.Fd statfs 2 "get file system statistics
statfs(path, buf);
char *path; struct statfs *buf;
.DE
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd fstatfs 2 "get file system statistics
fstatfs(fd, buf);
int fd; struct statfs *buf;
.DE
.Sh 3 "Creation and removal
.PP
The filesystem allows directories, files, special devices,
and fifos to be created and removed from the filesystem.
.Sh 4 "Directory creation and removal
.LP
A directory is created with the
.Fn mkdir
system call:
.DS
.Fd mkdir 2 "make a directory file
1994-06-19 04:07:16 +04:00
mkdir(path, mode);
1997-10-17 13:49:00 +04:00
char *path; mode_t mode;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
where the mode is defined as for files (see section
.Xr 2.2.3.2 ).
Directories are removed with the
.Fn rmdir
system call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd rmdir 1 "remove a directory file
1994-06-19 04:07:16 +04:00
rmdir(path);
char *path;
.DE
1997-10-17 13:49:00 +04:00
A directory must be empty (other than the entries ``.'' and ``..'')
if it is to be deleted.
.LP
Although directories can be read as files,
the usual interface is to use the call:
.DS
.Fd getdirentries 4 "get directory entries in a filesystem independent format
getdirentries(fd, buf, nbytes, basep);
int fd; char *buf; int nbytes; long *basep;
.DE
The
.Fn getdirentries
system call returns a canonical array of directory entries
in the filesystem independent format described in \fI<dirent.h>\fP.
Application programs usually use the library routines
.Fn opendir ,
.Fn readdir ,
and
.Fn closedir
which provide a more convenient interface than
.Fn getdirentries .
The \fIfts\fP package is provided
for recursive directory traversal.
.Sh 4 "File creation
.LP
Files are opened and/or created with the
.Fn open
system call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd open 3 "open or create a file for reading or writing
1994-06-19 04:07:16 +04:00
fd = open(path, oflag, mode);
1997-10-17 13:49:00 +04:00
result int fd; char *path; int oflag; mode_t mode;
1994-06-19 04:07:16 +04:00
.DE
The \fIpath\fP parameter specifies the name of the
1997-10-17 13:49:00 +04:00
file to be opened.
The \fIoflag\fP parameter must
include O_CREAT to cause the file to be created.
1994-06-19 04:07:16 +04:00
Bits for \fIoflag\fP are
1999-02-12 18:04:00 +03:00
defined in \fI<fcntl.h>\fP:
1997-10-17 13:49:00 +04:00
.DS
.TS
l l.
O_RDONLY /* open for reading only */
O_WRONLY /* open for writing only */
O_RDWR /* open for reading and writing */
O_NONBLOCK /* no delay */
O_APPEND /* set append mode */
O_SHLOCK /* open with shared file lock */
O_EXLOCK /* open with exclusive file lock */
O_ASYNC /* signal pgrp when data ready */
O_FSYNC /* synchronous writes */
O_CREAT /* create if nonexistent */
O_TRUNC /* truncate to zero length */
O_EXCL /* error if already exists */
.TE
1994-06-19 04:07:16 +04:00
.DE
.PP
One of O_RDONLY, O_WRONLY and O_RDWR should be specified,
1997-10-17 13:49:00 +04:00
indicating what types of operations are desired to be done
1994-06-19 04:07:16 +04:00
on the open file. The operations will be checked against the user's
1997-10-17 13:49:00 +04:00
access rights to the file before allowing the
.Fn open
to succeed.
Specifying O_APPEND causes all writes to be appended to the file.
Specifying O_TRUNC causes the file to be truncated when opened.
The flag O_CREAT causes the file to be created if it does not exist,
owned by the current user and the group of the containing directory.
The permissions for the new file are specified in \fImode\fP
as the OR of the appropriate permissions as defined in \fI<sys/stat.h>\fP:
.DS
.TS
l l.
S_IRWXU /* RWX for owner */
S_IRUSR /* R for owner */
S_IWUSR /* W for owner */
S_IXUSR /* X for owner */
S_IRWXG /* RWX for group */
S_IRGRP /* R for group */
S_IWGRP /* W for group */
S_IXGRP /* X for group */
S_IRWXO /* RWX for other */
S_IROTH /* R for other */
S_IWOTH /* W for other */
S_IXOTH /* X for other */
S_ISUID /* set user id */
S_ISGID /* set group id */
S_ISTXT /* sticky bit */
.TE
.DE
.LP
Historically, the file mode has been used as a four digit octal number.
The bottom three digits encode read access as 4, write access as 2 and
execute access as 1, or'ed together.
The 0700 bits describe owner access, the 070 bits describe the access
rights for processes in the same group as the file, and the 07 bits
describe the access rights for other processes.
The 7000 bits encode set user ID as 4000, set group ID as 2000, and the
sticky bit as 1000.
The mode specified to
.Fn open
is modified by
the process \fIumask\fP; permissions specified in the
\fIumask\fP are cleared in the mode of the created file.
The \fIumask\fP can be changed with the call:
.DS
.Fd umask 1 "set file creation mode mask
oldmask = umask(newmask);
result mode_t oldmask; mode_t newmask;
.DE
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
If the O_EXCL flag is set, and the file already exists, then the
.Fn open
will fail without affecting the file in any way.
This mechanism provides a simple exclusive access facility.
For security reasons,
if the O_EXCL flag is set and the file is a symbolic link,
the open will fail regardless of the existence of the file
referenced by the link.
The O_SHLOCK and O_EXLOCK flags allow the file to be atomically
.Fn open 'ed
and
.Fn flock 'ed;
see section
.Xr 2.2.7
for the semantics of
.Fn flock
style locks.
The O_ASYNC flag enables the SIGIO signal to be sent to
the process group of the opening process when I/O is possible,
e.g., upon availability of data to be read.
.Sh 4 "Creating references to devices
.PP
The filesystem allows entries which reference peripheral devices.
1994-06-19 04:07:16 +04:00
Peripherals are distinguished as \fIblock\fP or \fIcharacter\fP
devices according by their ability to support block-oriented
operations.
Devices are identified by their ``major'' and ``minor''
device numbers. The major device number determines the kind
of peripheral it is, while the minor device number indicates
1997-10-17 13:49:00 +04:00
either one of possibly many peripherals of that kind, or special
characteristics of the peripheral.
Structured devices have all operations done internally
in ``block'' quantities while unstructured devices
may have input and output done in varying units, and
may act as a non-seekable communications channel rather than a random-access
device.
The
.Fn mknod
call creates special entries:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd mknod 3 "make a special file node
1994-06-19 04:07:16 +04:00
mknod(path, mode, dev);
1997-10-17 13:49:00 +04:00
char *path; mode_t mode; dev_t dev;
1994-06-19 04:07:16 +04:00
.DE
where \fImode\fP is formed from the object type
and access permissions. The parameter \fIdev\fP is a configuration
dependent parameter used to identify specific character or
block I/O devices.
1997-10-17 13:49:00 +04:00
.LP
Fifo's can be created in the filesystem using the call:
.DS
.Fd mkfifo 2 "make a fifo file
mkfifo(path, mode);
char *path; mode_t mode;
.DE
The \fImode\fP parameter is used solely to specify the access
permissions of the newly created fifo.
.Sh 4 "Links and renaming
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
Links allow multiple names for a file to exist.
Links exist independently of the file to which they are linked.
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
Two types of links exist, \fIhard\fP links and \fIsymbolic\fP
links. A hard link is a reference counting mechanism that
allows a file to have multiple names within the same filesystem.
Each link to a file is equivalent, referring to the file independently
of any other name.
Symbolic links cause string substitution
during the pathname interpretation process, and refer to a file name
rather than referring directly to a file.
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
Hard links and symbolic links have different
properties. A hard link ensures that the target
file will always be accessible, even after its original
directory entry is removed; no such guarantee exists for a symbolic link.
Unlike hard links,
symbolic links can refernce directories and span filesystems boundaries.
An
.Fn lstat
(see section
.Xr 2.2.4 )
call on a hard link will return the information about the
file (or directory) that the link references while an
.Fn lstat
call on a symbolic link will return information about the link itself.
A symbolic link does not have an owner,
group, permissions, access and modification times, etc.
The only attributes returned from an
.Fn lstat
that refer to the symbolic link itself
are the file type (S_IFLNK), size, blocks, and link count (always 1).
The other attributes are filled in from
the directory that contains the link.
.LP
The following calls create a new link, named \fIpath2\fP,
to \fIpath1\fP:
.DS
.Fd link 2 "make a hard file link
link(path1, path2);
char *path1, *path2;
.DE
.DS
.Fd symlink 2 "make a symbolic link to a file
symlink(path1, path2);
char *path1, *path2;
.DE
The
.Fn unlink
primitive may be used to remove
either type of link.
.LP
If a file is a symbolic link, the ``value'' of the
link may be read with the
.Fn readlink
call:
.DS
.Fd readlink 3 "read value of a symbolic link
len = readlink(path, buf, bufsize);
result int len; char *path; result char *buf; int bufsize;
.DE
This call returns, in \fIbuf\fP, the string substituted into
pathnames passing through \fIpath\fP\|.
(This string is not NULL terminated.)
.LP
Atomic renaming of filesystem resident objects is possible with the
.Fn rename
call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd rename 2 "change the name of a file
rename(oldname, newname);
char *oldname, *newname;
.DE
where both \fIoldname\fP and \fInewname\fP must be
in the same filesystem.
If either \fIoldname\fP or \fInewname\fP is a directory,
then the other also must be a directory for the
.Fn rename
to succeed.
If \fInewname\fP exists and is a directory, then it must be empty.
.Sh 4 "File, device, and fifo removal
.LP
A reference to a file, special device or fifo may be removed with the
.Fn unlink
call:
.DS
.Fd unlink 1 "remove directory entry
1994-06-19 04:07:16 +04:00
unlink(path);
char *path;
.DE
The caller must have write access to the directory in which
the file is located for this call to be successful.
1997-10-17 13:49:00 +04:00
When the last name for a file has been removed, the file may no longer
be opened; the file itself is removed once any existing references
have been closed.
.LP
All current access to a file can be revoked using the call:
.DS
.Fd revoke 1 "revoke file access
revoke(path);
char *path;
.DE
Subsequent operations on any descriptors open at the time of the
.Fn revoke
fail, with the exceptions that a
.Fn close
call will succeed, and a
.Fn read
from a character device file which has been revoked returns a count
of zero (end of file).
If the file is a special file for a device which is open,
the device close function is called as if all open references
to the file had been closed.
.Fn Open 's
done after the
.Fn revoke
may succeed.
This call is most useful for revoking access to a terminal line after
a hangup in preparation for reuse by a new login session.
Access to a controlling terminal is automatically revoked
when the session leader for the session exits.
.Sh 3 "Reading and modifying file attributes
.LP
1994-06-19 04:07:16 +04:00
Detailed information about the attributes of a file
may be obtained with the calls:
.DS
1997-10-17 13:49:00 +04:00
.Fd stat 2 "get file status
1994-06-19 04:07:16 +04:00
stat(path, stb);
char *path; result struct stat *stb;
1997-10-17 13:49:00 +04:00
.DE
.DS
.Fd fstat 2 "get file status
1994-06-19 04:07:16 +04:00
fstat(fd, stb);
int fd; result struct stat *stb;
.DE
The \fIstat\fP structure includes the file
type, protection, ownership, access times,
size, and a count of hard links.
If the file is a symbolic link, then the status of the link
itself (rather than the file the link references)
1997-10-17 13:49:00 +04:00
may be obtained using the
.Fn lstat
call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd lstat 2 "get file status
1994-06-19 04:07:16 +04:00
lstat(path, stb);
char *path; result struct stat *stb;
.DE
.PP
1997-10-17 13:49:00 +04:00
Newly created files are assigned the user ID of the process that created
them and the group ID of the directory in which they were created.
The ownership of a file may be changed by either of the calls:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd chown 3 "change owner and group of a file
1994-06-19 04:07:16 +04:00
chown(path, owner, group);
1997-10-17 13:49:00 +04:00
char *path; uid_t owner; gid_t group;
.DE
.DS
.Fd fchown 3 "change owner and group of a file
1994-06-19 04:07:16 +04:00
fchown(fd, owner, group);
1997-10-17 13:49:00 +04:00
int fd, uid_t owner; gid_t group;
1994-06-19 04:07:16 +04:00
.DE
.PP
In addition to ownership, each file has three levels of access
protection associated with it. These levels are owner relative,
1997-10-17 13:49:00 +04:00
group relative, and other.
Each level of access has separate indicators for read permission,
write permission, and execute permission.
1994-06-19 04:07:16 +04:00
The protection bits associated with a file may be set by either
of the calls:
.DS
1997-10-17 13:49:00 +04:00
.Fd chmod 2 "change mode of file
1994-06-19 04:07:16 +04:00
chmod(path, mode);
1997-10-17 13:49:00 +04:00
char *path; mode_t mode;
.DE
.DS
.Fd fchmod 2 "change mode of file
1994-06-19 04:07:16 +04:00
fchmod(fd, mode);
1997-10-17 13:49:00 +04:00
int fd, mode_t mode;
1994-06-19 04:07:16 +04:00
.DE
where \fImode\fP is a value indicating the new protection
1997-10-17 13:49:00 +04:00
of the file, as listed in section
.Xr 2.2.3.2 .
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
Each file has a set of flags stored as a bit mask associated with it.
These flags are returned in the \fIstat\fP structure and
are set using the calls:
.DS
.Fd chflags 2 "set file flags
chflags(path, flags);
char *path; u_long flags;
.DE
.DS
.Fd fchflags 2 "set file flags
fchflags(fd, flags);
int fd; u_long flags;
.DE
.ne 1i
The flags specified are formed by or'ing the following values:
.DS
.TS
l l.
UF_NODUMP Do not dump the file.
UF_IMMUTABLE The file may not be changed.
UF_APPEND The file may only be appended to.
SF_IMMUTABLE The file may not be changed.
SF_APPEND The file may only be appended to.
.TE
.DE
The UF_NODUMP, UF_IMMUTABLE and UF_APPEND
flags may be set or unset by either the owner of a file or the super-user.
The SF_IMMUTABLE and SF_APPEND
flags may only be set or unset by the super-user.
They may be set at any time, but normally may only be unset when
the system is in single-user mode.
.LP
1994-06-19 04:07:16 +04:00
Finally, the access and modify times on a file may be set by the call:
.DS
1997-10-17 13:49:00 +04:00
.Fd utimes 2 "set file access and modification times
utimes(path, tvp);
1994-06-19 04:07:16 +04:00
char *path; struct timeval *tvp[2];
.DE
1997-10-17 13:49:00 +04:00
This is particularly useful when moving files between media,
to preserve file access and modification times.
.Sh 3 "Checking accessibility
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
A process running with
different real and effective user-ids
may interrogate the accessibility of a file to the
real user by using the
.Fn access
call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd access 2 "check access permissions of a file or pathname
accessible = access(path, how);
result int accessible; char *path; int how;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
\fIHow\fP is constructed by OR'ing the following bits, defined
in \fI<unistd.h>\fP:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.TS
l l.
F_OK /* file exists */
X_OK /* file is executable/searchable */
W_OK /* file is writable */
R_OK /* file is readable */
.TE
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
The presence or absence of advisory locks does not affect the
result of
.Fn access .
.PP
The
.Fn pathconf
and
.Fn fpathconf
functions provide a method for applications to determine the current
value of a configurable system limit or option variable associated
with a pathname or file descriptor:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd pathconf 2 "get configurable pathname variables
ans = pathconf(path, name);
result long ans; char *path; int name;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
.DS
.Fd fpathconf 2 "get configurable pathname variables
ans = fpathconf(fd, name);
result long ans; int fd, name;
.DE
For
.Fn pathconf ,
the \fIpath\fP argument is the name of a file or directory.
For
.Fn fpathconf ,
the \fIfd\fP argument is an open file descriptor.
The \fIname\fP argument specifies the system variable to be queried.
Symbolic constants for each name value are found in the include file
\fI<unistd.h>\fP.
.Sh 3 "Extension and truncation
1994-06-19 04:07:16 +04:00
.PP
Files are created with zero length and may be extended
simply by writing or appending to them. While a file is
open the system maintains a pointer into the file
indicating the current location in the file associated with
the descriptor. This pointer may be moved about in the
file in a random access fashion.
1997-10-17 13:49:00 +04:00
To set the current offset into a file, the
.Fn lseek
call may be used:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd lseek 3 "reposition read/write file offset
1994-06-19 04:07:16 +04:00
oldoffset = lseek(fd, offset, type);
result off_t oldoffset; int fd; off_t offset; int type;
.DE
1997-10-17 13:49:00 +04:00
.ne 1i
where \fItype\fP is defined by \fI<unistd.h>\fP as one of:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.TS
l l.
SEEK_SET /* set file offset to offset */
SEEK_CUR /* set file offset to current plus offset */
SEEK_END /* set file offset to EOF plus offset */
.TE
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
The call ``lseek(fd, 0, SEEK_CUR)''
1994-06-19 04:07:16 +04:00
returns the current offset into the file.
.PP
1997-10-17 13:49:00 +04:00
Files may have ``holes'' in them.
Holes are areas in the linear extent of the file where data has never
been written.
These may be created by seeking to a location in a file past the
current end-of-file and writing.
1994-06-19 04:07:16 +04:00
Holes are treated by the system as zero valued bytes.
1997-10-17 13:49:00 +04:00
.LP
A file may be extended or truncated with either of the calls:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd truncate 2 "truncate a file to a specified length
1994-06-19 04:07:16 +04:00
truncate(path, length);
1997-10-17 13:49:00 +04:00
char *path; off_t length;
1994-06-19 04:07:16 +04:00
.DE
.DS
1997-10-17 13:49:00 +04:00
.Fd ftruncate 2 "truncate a file to a specified length
ftruncate(fd, length);
int fd; off_t length;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
changing the size of the specified file to \fIlength\fP bytes.
.PP
Unless opened with the O_FSYNC flag,
writes to files are held for an indeterminate period of time
in the system buffer cache.
The call:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd fsync 1 "synchronize in-core state of a file with that on disk
fsync(fd);
int fd;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
ensures that the contents of a file are committed to disk
before returning.
This feature is used by applications such as editors that
want to ensure the integrity of a new file before continuing.
.Sh 3 "Locking
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
The filesystem provides basic facilities that allow cooperating processes
1994-06-19 04:07:16 +04:00
to synchronize their access to shared files. A process may
place an advisory \fIread\fP or \fIwrite\fP lock on a file,
so that other cooperating processes may avoid interfering
with the process' access. This simple mechanism
1997-10-17 13:49:00 +04:00
provides locking with file granularity.
Byte range locking is available with
.Fn fcntl ;
see section
.Xr 1.5.4 .
1994-06-19 04:07:16 +04:00
The system does not force processes to obey the locks;
they are of an advisory nature only.
1997-10-17 13:49:00 +04:00
.LP
Locking can be done as part of the
.Fn open
call (see section
.Xr 2.2.3.2 )
or after an
.Fn open
call by applying the
.Fn flock
primitive:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd flock 2 "apply or remove an advisory lock on an open file
1994-06-19 04:07:16 +04:00
flock(fd, how);
int fd, how;
.DE
1997-10-17 13:49:00 +04:00
where the \fIhow\fP parameter is formed from bits
defined in \fI<fcntl.h>\fP:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.TS
l l.
LOCK_SH /* shared file lock */
LOCK_EX /* exclusive file lock */
LOCK_NB /* don't block when locking */
LOCK_UN /* unlock file */
.TE
1994-06-19 04:07:16 +04:00
.DE
Successive lock calls may be used to increase or
decrease the level of locking. If an object is currently
1997-10-17 13:49:00 +04:00
locked by another process when a
.Fn flock
call is made, the caller will be blocked until the current lock owner
1994-06-19 04:07:16 +04:00
releases the lock; this may be avoided by including LOCK_NB
in the \fIhow\fP parameter.
Specifying LOCK_UN removes all locks associated with the descriptor.
Advisory locks held by a process are automatically deleted when
the process terminates.
1997-10-17 13:49:00 +04:00
.Sh 3 "Disk quotas
1994-06-19 04:07:16 +04:00
.PP
1997-10-17 13:49:00 +04:00
As an optional facility, each local filesystem can impose limits on a
user's or group's disk usage.
1994-06-19 04:07:16 +04:00
Two quantities are limited: the total amount of disk space which
1997-10-17 13:49:00 +04:00
a user or group may allocate in a filesystem and the total number of files
a user or group may create in a filesystem. Quotas are expressed as
1994-06-19 04:07:16 +04:00
\fIhard\fP limits and \fIsoft\fP limits. A hard limit is
1997-10-17 13:49:00 +04:00
always imposed; if a user or group would exceed a hard limit, the operation
1994-06-19 04:07:16 +04:00
which caused the resource request will fail. A soft limit results
1997-10-17 13:49:00 +04:00
in the user or group receiving a warning message,
but with allocation succeeding.
1994-06-19 04:07:16 +04:00
Facilities are provided to turn soft limits into hard limits if a
1997-10-17 13:49:00 +04:00
user or group has exceeded a soft limit for an unreasonable period of time.
.LP
The
.Fn quotactl
call enables, disables and manipulates filesystem quotas:
1994-06-19 04:07:16 +04:00
.DS
1997-10-17 13:49:00 +04:00
.Fd quotactl 4 "manipulate filesystem quotas
quotactl(path, cmd, id, addr);
char *path; int cmd; int id; char *addr;
1994-06-19 04:07:16 +04:00
.DE
1997-10-17 13:49:00 +04:00
A quota control command given by cmd operates on the given filename path
for the given user ID. The address of an optional command specific data
structure, addr, may be given.
The supported commands include:
.DS
.TS
l l.
Q_QUOTAON /* enable quotas */
Q_QUOTAOFF /* disable quotas */
Q_GETQUOTA /* get limits and usage */
Q_SETQUOTA /* set limits and usage */
Q_SETUSE /* set usage */
Q_SYNC /* sync disk copy of a filesystems quotas */
.TE
.DE
.Sh 3 "Remote filesystems
.LP
There are two system calls intended to help support the remote filesystem
implementation.
The call:
.DS
.Fd nfssvc 2 "NFS services
nfssvc(flags, argstructp);
int flags, void *argstructp;
.DE
is used by the NFS daemons to pass information into
and out of the kernel and also to enter the kernel as a server daemon.
The flags argument consists of several bits that show what action is to
be taken once in the kernel and \fIargstructp\fP points to one of three
structures depending on which bits are set in flags.
.LP
The call:
.DS
.Fd getfh 2 "get file handle
getfh(path, fhp);
char *path; result fhandle_t *fhp;
.DE
returns a file handle for the specified file or directory in the
file handle pointed to by fhp.
This file handle can then be used in future calls to NFS to access
the file without the need to repeat the pathname translation.
This system call is restricted to the superuser.
.Sh 3 "Other filesystems
.LP
The kernel supports many other filesystems.
These include:
.IP \(bu
The log-structured filesystem. It provides an alternate disk
layout than the fast filesystem optimized for writing rather
than reading.
For further information see the
.Xr mount_lfs (8)
manual page.
.\"
.\" We currently do not document the LFS calls
.\" .Fd lfs_bmapv 3
.\" .Fd lfs_markv 3
.\" .Fd lfs_segclean 2
.\" .Fd lfs_segwait 2
.IP \(bu
The ISO-standard 9660 filesystem with Rock Ridge extensions used for CD-ROMs.
For further information see the
.Xr mount_cd9660 (8)
manual page.
.IP \(bu
The file descriptor mapping filesystem.
For further information see the
.Xr mount_fdesc (8)
manual page.
.IP \(bu
The /proc filesystem as an alternative for debuggers.
For further information see section
.Xr 2.5.1
and the
.Xr mount_procfs (8)
manual page.
.IP \(bu
The memory-based filesystem,
used primarily for fast but ethereal uses such as /tmp.
For further information see the
.Xr mount_mfs (8)
manual page.
.IP \(bu
The kernel variable filesystem, used as an alternative to
.Fn sysctl .
For further information see section
.Xr 1.7.1
and the
.Xr mount_kernfs (8)
manual page.
.IP \(bu
The portal filesystem, used to mount processes in the filesystem.
For further information see the
.Xr mount_portal (8)
manual page.
.IP \(bu
The uid/gid remapping filesystem, usually layered above NFS filesystems
exported to an outside administrative domain.
For further information see the
.Xr mount_umap (8)
manual page.
.IP \(bu
The union filesystem, used to place a writable filesystem above
a read-only filesystem.
This filesystem is useful for compiling sources on a CD-ROM
without having to copy the CD-ROM contents to writable disk.
For further information see the
.Xr mount_union (8)
manual page.