| .\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) |
| .\" |
| .\" %%%LICENSE_START(VERBATIM) |
| .\" 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. |
| .\" %%%LICENSE_END |
| .\" |
| .TH PATH_RESOLUTION 7 2017-11-26 "Linux" "Linux Programmer's Manual" |
| .SH NAME |
| path_resolution \- how a pathname is resolved to a file |
| .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\(emor one of its ancestors\(emwas 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. |
| .PP |
| 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.) |
| .PP |
| 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 nonfinal 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. |
| .PP |
| If the process does not have search permission on |
| the current lookup directory, |
| an |
| .B EACCES |
| error is returned ("Permission denied"). |
| .PP |
| If the component is not found, an |
| .B ENOENT |
| error is returned |
| ("No such file or directory"). |
| .PP |
| If the component is found, but is neither a directory nor a symbolic link, |
| an |
| .B ENOTDIR |
| error is returned ("Not a directory"). |
| .PP |
| If the component is found and is a directory, we set the |
| current lookup directory to that directory, and go to the |
| next component. |
| .PP |
| 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 can involve recursion if the |
| prefix ('dirname') component of a pathname contains a filename |
| that is a symbolic link that resolves to a directory (where the |
| prefix component of that directory may contain a symbolic link, and so on). |
| 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"). |
| .PP |
| .\" |
| .\" presently: max recursion depth during symlink resolution: 5 |
| .\" max total number of symbolic links followed: 40 |
| .\" _POSIX_SYMLOOP_MAX is 8 |
| As currently implemented on Linux, the maximum number |
| .\" MAXSYMLINKS is 40 |
| of symbolic links that will be followed while resolving a pathname is 40. |
| In kernels before 2.6.18, the limit on the recursion depth was 5. |
| Starting with Linux 2.6.18, this limit |
| .\" MAX_NESTED_LINKS |
| was raised to 8. |
| In Linux 4.2, |
| .\" commit 894bc8c4662ba9daceafe943a5ba0dd407da5cd3 |
| the kernel's pathname-resolution code |
| was reworked to eliminate the use of recursion, |
| so that the only limit that remains is the maximum of 40 |
| resolutions for the entire pathname. |
| .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\(emit may have to be a directory, or a nondirectory, because of |
| the requirements of the specific system call), and (ii) it |
| is not necessarily an error if the component is not found\(emmaybe |
| 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. |
| .PP |
| The path resolution process will assume that these entries have |
| their conventional meanings, regardless of whether they are |
| actually present in the physical filesystem. |
| .PP |
| 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. |
| .PP |
| 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 \(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 ("Filename 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; see |
| .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. |
| .PP |
| 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. |
| .PP |
| 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). |
| .PP |
| (Here "fsuid" stands for something like "filesystem 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).) |
| .PP |
| Similarly, Linux uses the fsgid ("filesystem 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) |
| .PP |
| On Linux, superuser privileges are divided into capabilities (see |
| .BR capabilities (7)). |
| Two capabilities are relevant for file permissions checks: |
| .B CAP_DAC_OVERRIDE |
| and |
| .BR CAP_DAC_READ_SEARCH . |
| (A process has these capabilities if its fsuid is 0.) |
| .PP |
| The |
| .B CAP_DAC_OVERRIDE |
| capability overrides all permission checking, |
| but grants execute permission only when at least one |
| of the file's three execute permission bits is set. |
| .PP |
| The |
| .B 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 readlink (2), |
| .BR capabilities (7), |
| .BR credentials (7), |
| .BR symlink (7) |