mirror of https://github.com/mkerrisk/man-pages
233 lines
9.1 KiB
Groff
233 lines
9.1 KiB
Groff
.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl)
|
|
.\"
|
|
.\" Permission is granted to make and distribute verbatim copies of this
|
|
.\" manual provided the copyright notice and this permission notice are
|
|
.\" preserved on all copies.
|
|
.\"
|
|
.\" Permission is granted to copy and distribute modified versions of this
|
|
.\" manual under the conditions for verbatim copying, provided that the
|
|
.\" entire resulting derived work is distributed under the terms of a
|
|
.\" permission notice identical to this one.
|
|
.\"
|
|
.\" Since the Linux kernel and libraries are constantly changing, this
|
|
.\" manual page may be incorrect or out-of-date. The author(s) assume no
|
|
.\" responsibility for errors or omissions, or for damages resulting from
|
|
.\" the use of the information contained herein. The author(s) may not
|
|
.\" have taken the same level of care in the production of this manual,
|
|
.\" which is licensed free of charge, as they might when working
|
|
.\" professionally.
|
|
.\"
|
|
.\" Formatted or processed versions of this manual, if unaccompanied by
|
|
.\" the source, must acknowledge the copyright and authors of this work.
|
|
.\"
|
|
.TH PATH_RESOLUTION 7 2008-11-20 "Linux" "Linux Programmer's Manual"
|
|
.SH NAME
|
|
Unix/Linux path resolution \- find the file referred to by a filename
|
|
.SH DESCRIPTION
|
|
Some Unix/Linux system calls have as parameter one or more filenames.
|
|
A filename (or pathname) is resolved as follows.
|
|
.SS "Step 1: Start of the resolution process"
|
|
If the pathname starts with the \(aq/\(aq character,
|
|
the starting lookup directory
|
|
is the root directory of the calling process.
|
|
(A process inherits its
|
|
root directory from its parent.
|
|
Usually this will be the root directory
|
|
of the file hierarchy.
|
|
A process may get a different root directory
|
|
by use of the
|
|
.BR chroot (2)
|
|
system call.
|
|
A process may get an entirely private mount namespace in case
|
|
it \(em or one of its ancestors \(em was started by an invocation of the
|
|
.BR clone (2)
|
|
system call that had the
|
|
.B CLONE_NEWNS
|
|
flag set.)
|
|
This handles the \(aq/\(aq part of the pathname.
|
|
|
|
If the pathname does not start with the \(aq/\(aq character, the
|
|
starting lookup directory of the resolution process is the current working
|
|
directory of the process.
|
|
(This is also inherited from the parent.
|
|
It can be changed by use of the
|
|
.BR chdir (2)
|
|
system call.)
|
|
|
|
Pathnames starting with a \(aq/\(aq character are called absolute pathnames.
|
|
Pathnames not starting with a \(aq/\(aq are called relative pathnames.
|
|
.SS "Step 2: Walk along the path"
|
|
Set the current lookup directory to the starting lookup directory.
|
|
Now, for each non-final component of the pathname, where a component
|
|
is a substring delimited by \(aq/\(aq characters, this component is looked up
|
|
in the current lookup directory.
|
|
|
|
If the process does not have search permission on
|
|
the current lookup directory,
|
|
an
|
|
.B EACCES
|
|
error is returned ("Permission denied").
|
|
|
|
If the component is not found, an
|
|
.B ENOENT
|
|
error is returned
|
|
("No such file or directory").
|
|
|
|
If the component is found, but is neither a directory nor a symbolic link,
|
|
an
|
|
.B ENOTDIR
|
|
error is returned ("Not a directory").
|
|
|
|
If the component is found and is a directory, we set the
|
|
current lookup directory to that directory, and go to the
|
|
next component.
|
|
|
|
If the component is found and is a symbolic link (symlink), we first
|
|
resolve this symbolic link (with the current lookup directory
|
|
as starting lookup directory).
|
|
Upon error, that error is returned.
|
|
If the result is not a directory, an
|
|
.B ENOTDIR
|
|
error is returned.
|
|
If the resolution of the symlink is successful and returns a directory,
|
|
we set the current lookup directory to that directory, and go to
|
|
the next component.
|
|
Note that the resolution process here involves recursion.
|
|
In order to protect the kernel against stack overflow, and also
|
|
to protect against denial of service, there are limits on the
|
|
maximum recursion depth, and on the maximum number of symbolic links
|
|
followed.
|
|
An
|
|
.B ELOOP
|
|
error is returned when the maximum is
|
|
exceeded ("Too many levels of symbolic links").
|
|
.\"
|
|
.\" presently: max recursion depth during symlink resolution: 5
|
|
.\" max total number of symbolic links followed: 40
|
|
.\" _POSIX_SYMLOOP_MAX is 8
|
|
.SS "Step 3: Find the final entry"
|
|
The lookup of the final component of the pathname goes just like
|
|
that of all other components, as described in the previous step,
|
|
with two differences: (i) the final component need not be a
|
|
directory (at least as far as the path resolution process is concerned \(em
|
|
it may have to be a directory, or a non-directory, because of
|
|
the requirements of the specific system call), and (ii) it
|
|
is not necessarily an error if the component is not found \(em
|
|
maybe we are just creating it.
|
|
The details on the treatment
|
|
of the final entry are described in the manual pages of the specific
|
|
system calls.
|
|
.SS ". and .."
|
|
By convention, every directory has the entries "." and "..",
|
|
which refer to the directory itself and to its parent directory,
|
|
respectively.
|
|
|
|
The path resolution process will assume that these entries have
|
|
their conventional meanings, regardless of whether they are
|
|
actually present in the physical file system.
|
|
|
|
One cannot walk down past the root: "/.." is the same as "/".
|
|
.SS "Mount points"
|
|
After a "mount dev path" command, the pathname "path" refers to
|
|
the root of the file system hierarchy on the device "dev", and no
|
|
longer to whatever it referred to earlier.
|
|
|
|
One can walk out of a mounted file system: "path/.." refers to
|
|
the parent directory of "path",
|
|
outside of the file system hierarchy on "dev".
|
|
.SS "Trailing slashes"
|
|
If a pathname ends in a \(aq/\(aq, that forces resolution of the preceding
|
|
component as in Step 2: it has to exist and resolve to a directory.
|
|
Otherwise a trailing \(aq/\(aq is ignored.
|
|
(Or, equivalently, a pathname with a trailing \(aq/\(aq is equivalent to
|
|
the pathname obtained by appending \(aq.\(aq to it.)
|
|
.SS "Final symlink"
|
|
If the last component of a pathname is a symbolic link, then it
|
|
depends on the system call whether the file referred to will be
|
|
the symbolic link or the result of path resolution on its contents.
|
|
For example, the system call
|
|
.BR lstat (2)
|
|
will operate on the symlink, while
|
|
.BR stat (2)
|
|
operates on the file pointed to by the symlink.
|
|
.SS "Length limit"
|
|
There is a maximum length for pathnames.
|
|
If the pathname (or some
|
|
intermediate pathname obtained while resolving symbolic links)
|
|
is too long, an
|
|
.B ENAMETOOLONG
|
|
error is returned ("File name too long").
|
|
.SS "Empty pathname"
|
|
In the original Unix, the empty pathname referred to the current directory.
|
|
Nowadays POSIX decrees that an empty pathname must not be resolved
|
|
successfully.
|
|
Linux returns
|
|
.B ENOENT
|
|
in this case.
|
|
.SS "Permissions"
|
|
The permission bits of a file consist of three groups of three bits, cf.\&
|
|
.BR chmod (1)
|
|
and
|
|
.BR stat (2).
|
|
The first group of three is used when the effective user ID of
|
|
the calling process equals the owner ID of the file.
|
|
The second group
|
|
of three is used when the group ID of the file either equals the
|
|
effective group ID of the calling process, or is one of the
|
|
supplementary group IDs of the calling process (as set by
|
|
.BR setgroups (2)).
|
|
When neither holds, the third group is used.
|
|
|
|
Of the three bits used, the first bit determines read permission,
|
|
the second write permission, and the last execute permission
|
|
in case of ordinary files, or search permission in case of directories.
|
|
|
|
Linux uses the fsuid instead of the effective user ID in permission checks.
|
|
Ordinarily the fsuid will equal the effective user ID, but the fsuid can be
|
|
changed by the system call
|
|
.BR setfsuid (2).
|
|
|
|
(Here "fsuid" stands for something like "file system user ID".
|
|
The concept was required for the implementation of a user space
|
|
NFS server at a time when processes could send a signal to a process
|
|
with the same effective user ID.
|
|
It is obsolete now.
|
|
Nobody should use
|
|
.BR setfsuid (2).)
|
|
|
|
Similarly, Linux uses the fsgid ("file system group ID")
|
|
instead of the effective group ID.
|
|
See
|
|
.BR setfsgid (2).
|
|
.\" FIXME say something about file system mounted read-only ?
|
|
.SS "Bypassing permission checks: superuser and capabilities"
|
|
On a traditional Unix system, the superuser
|
|
.RI ( root ,
|
|
user ID 0) is all-powerful, and bypasses all permissions restrictions
|
|
when accessing files.
|
|
.\" (but for exec at least one x bit must be set) -- AEB
|
|
.\" but there is variation across systems on this point: for
|
|
.\" example, HP-UX and Tru64 are as described by AEB. However,
|
|
.\" on some implementations (e.g., Solaris, FreeBSD),
|
|
.\" access(X_OK) by superuser will report success, regardless
|
|
.\" of the file's execute permission bits. -- MTK (Oct 05)
|
|
|
|
On Linux, superuser privileges are divided into capabilities (see
|
|
.BR capabilities (7)).
|
|
Two capabilities are relevant for file permissions checks:
|
|
\fBCAP_DAC_OVERRIDE\fP and \fBCAP_DAC_READ_SEARCH\fP.
|
|
(A process has these capabilities if its fsuid is 0.)
|
|
|
|
The \fBCAP_DAC_OVERRIDE\fP capability overrides all permission checking,
|
|
but only grants execute permission when at least one
|
|
of the file's three execute permission bits is set.
|
|
|
|
The \fBCAP_DAC_READ_SEARCH\fP capability grants read and search permission
|
|
on directories, and read permission on ordinary files.
|
|
.\" FIXME say something about immutable files
|
|
.\" FIXME say something about ACLs
|
|
.SH "SEE ALSO"
|
|
.BR capabilities (7),
|
|
.BR credentials (7),
|
|
.BR symlink (7)
|