mirror of https://github.com/mkerrisk/man-pages
211 lines
8.9 KiB
Groff
211 lines
8.9 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 2 2004-06-21 "Linux 2.6.7" "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 '/' character, the starting lookup directory
|
|
is the root directory of the current 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 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 CLONE_NEWNS flag set.)
|
|
This handles the '/' part of the pathname.
|
|
|
|
If the pathname does not start with the '/' 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 '/' character are called absolute pathnames.
|
|
Pathnames not starting with a '/' 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 '/' 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 EACCES error is returned ("Permission denied").
|
|
|
|
If the component is not found, an ENOENT error is returned
|
|
("No such file or directory").
|
|
|
|
If the component is found, but is neither a directory nor a symbolic link,
|
|
an 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 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 symlinks
|
|
followed. An 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 symlinks 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 filesystem.
|
|
|
|
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 filesystem hierarchy on the device "dev", and no
|
|
longer to whatever it referred to earlier.
|
|
|
|
One can walk out of a mounted filesystem: "path/.." refers to
|
|
the parent directory of "path",
|
|
outside of the filesystem hierarchy on "dev".
|
|
|
|
.SS "Trailing slashes"
|
|
If a pathname ends in a '/', that forces resolution of the preceding
|
|
component as in Step 2: it has to exist and resolve to a directory.
|
|
Otherwise a trailing '/' is ignored.
|
|
(Or, equivalently, a pathname with a trailing '/' is equivalent to
|
|
the pathname obtained by appending '.' 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 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 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 current 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 current process, or is one of the
|
|
supplementary group IDs of the current 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 filesystem 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:
|
|
CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH.
|
|
(A process has these capabilities if its fsuid is 0.)
|
|
|
|
The CAP_DAC_OVERRIDE 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 CAP_DAC_READ_SEARCH 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)
|