PATH_RESOLUTION(2) Linux Programmer's Manual PATH_RESOLUTION(2)
NAME
Unix/Linux path resolution - find the file(1,n) referred to by a filename
DESCRIPTION
Some Unix/Linux system calls have as parameter one or more filenames.
A filename (or pathname) is resolved as follows.
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(1,n) hierarchy. A process may get a different
root directory by use of the chroot(1,2)(2) system call. A process may get
an entirely private namespace in(1,8) case it - or one of its ancestors -
was started by an invocation of the 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 chdir(2) system call.)
Pathnames starting with a '/' character are called absolute pathnames.
Pathnames not starting with a '/' are called relative pathnames.
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(1,8)
the current lookup directory.
If the process does not have search permission on the current lookup
directory, an EACCES error(8,n) is returned ("Permission denied").
If the component is not found, an ENOENT error(8,n) is returned ("No such
file(1,n) or directory").
If the component is found, but is neither a directory nor a symbolic
link(1,2), an ENOTDIR error(8,n) is returned ("Not a directory").
If the component is found and is a directory, we set(7,n,1 builtins) the current lookup
directory to that directory, and go to the next component.
If the component is found and is a symbolic link(1,2) (symlink), we first
resolve this symbolic link(1,2) (with the current lookup directory as start-
ing lookup directory). Upon error(8,n), that error(8,n) is returned. If the
result is not a directory, an ENOTDIR error(8,n) is returned. If the reso-
lution of the symlink is successful and returns a directory, we set(7,n,1 builtins) the
current lookup directory to that directory, and go to the next compo-
nent. 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(8,n)
is returned when the maximum is exceeded ("Too many levels of symbolic
links").
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(1,8) 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 - 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(8,n) if(3,n) the
component is not found - maybe we are just creating it. The details on
the treatment of the final entry are described in(1,8) the manual pages of
the specific system calls.
. and ..
By convention, every directory has the entries "." and "..", which
refer to the directory itself and to its parent directory, respec-
tively.
The path resolution process will assume that these entries have their
conventional meanings, regardless of whether they are actually present
in(1,8) the physical filesystem.
One cannot walk down past the root: "/.." is the same as "/".
Mount points
After a "mount(2,8) 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 par-
ent directy of "path", outside of the filesystem hierarchy on "dev".
Trailing slashes
If a pathname ends in(1,8) a '/', that forces resolution of the preceding
component as in(1,8) 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.)
Final symlink
If the last component of a pathname is a symbolic link(1,2), then it depends
on the system call whether the file(1,n) referred to will be the symbolic
link(1,2) or the result of path resolution on its contents. For example,
the system call lstat(2) will operate on the symlink, while stat(1,2)(2)
operates on the file(1,n) pointed to by the symlink.
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(8,n) is returned ("File name too long").
Empty pathname
In the original Unix, the empty pathname referred to the current direc-
tory. Nowadays POSIX decrees that an empty pathname must not be
resolved successfully. Linux returns ENOENT in(1,8) this case.
Permissions
The permission bits of a file(1,n) consist of three groups of three bits,
cf. chmod(1,2)(1) and stat(1,2)(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(1,n)
either equals the effective group ID of the current process, or is one
of the supplementary group IDs of the current process (as set(7,n,1 builtins) by set-
groups(2)). When neither holds, the third group is used.
Of the three bits used, the first bit determines read(2,n,1 builtins) permission, the
second write(1,2) permission, and the last execute permission in(1,8) case of
ordinary files, or search permission in(1,8) case of directories.
Linux uses the fsuid instead of the effective user ID in(1,8) permission
checks. Ordinarily the fsuid will equal the effective user ID, but the
fsuid can be changed by the system call setfsuid(2).
(Here "fsuid" stands for something like "file(1,n) system user ID". The
concept was required for the implementation of a user space NFS server
at a time(1,2,n) when processes could send(2,n) a signal(2,7) to a process with the same
effective user ID. It is obsolete now. Nobody should use setfsuid(2).)
Similarly, Linux uses the fsgid instead of the effective group ID. See
setfsgid(2).
Capabilities
If the permission bits of the file(1,n) deny whatever is asked, permission
can still be granted by the appropriate capabilities.
Traditional systems do not use capabilities and root (user ID 0) is
all-powerful. Such systems are presently (2.6.7) handled by giving root
all capabilities except for CAP_SETPCAP. More precisely, at exec(3,n,1 builtins) time(1,2,n) a
process gets(3,n) all capabilities except CAP_SETPCAP and the five capabili-
ties CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER,
CAP_FSETID, in(1,8) case it has zero euid, and it gets(3,n) these last five capa-
bilities in(1,8) case it has zero fsuid, while all other processes get no
capabilities.
The CAP_DAC_OVERRIDE capability overrides all permission checking, but
will only grant execute permission when at least one of the three exe-
cute permission bits is set.
The CAP_DAC_READ_SEARCH capability will grant read(2,n,1 builtins) and search permis-
sion on directories, and read(2,n,1 builtins) permission on ordinary files.
The CAP_SYS_ADMIN capability will (e.g.) allow a process to violate the
limit (visible in(1,8) /proc(5,n)/sys/fs/file-max) on the maximum number of open(2,3,n)
files in(1,8) the system, where a process lacking that capability would see
an ENFILE error(8,n) return.
SEE ALSO
capabilities(7)
Linux 2.6.7 2004-06-21 PATH_RESOLUTION(2)