| 1 |
.\" Copyright 2003, Andries E. Brouwer <[email protected]> |
| 2 |
.\" Copyright, the authors of the Linux man-pages project |
| 3 |
.\" |
| 4 |
.\" SPDX-License-Identifier: Linux-man-pages-copyleft |
| 5 |
.\" |
| 6 |
.TH path_resolution 7 2026-02-08 "Linux man-pages 6.18" |
| 7 |
.SH NAME |
| 8 |
path_resolution \- how a pathname is resolved to a file |
| 9 |
.SH DESCRIPTION |
| 10 |
Some UNIX/Linux system calls have as parameter one or more filenames. |
| 11 |
A filename (or pathname) is resolved as follows. |
| 12 |
.SS Step 1: start of the resolution process |
| 13 |
If the pathname starts with the \[aq]/\[aq] character, the starting lookup |
| 14 |
directory is the root directory of the calling process. |
| 15 |
A process inherits its root directory from its parent. |
| 16 |
Usually this will be the root directory of the file hierarchy. |
| 17 |
A process may get a different root directory by use of the |
| 18 |
.BR chroot (2) |
| 19 |
system call, or may temporarily use a different root directory by using |
| 20 |
.BR openat2 (2) |
| 21 |
with the |
| 22 |
.B RESOLVE_IN_ROOT |
| 23 |
flag set. |
| 24 |
.P |
| 25 |
A process may get an entirely private mount namespace in case |
| 26 |
it\[em]or one of its ancestors\[em]was started by an invocation of the |
| 27 |
.BR clone (2) |
| 28 |
system call that had the |
| 29 |
.B CLONE_NEWNS |
| 30 |
flag set. |
| 31 |
This handles the \[aq]/\[aq] part of the pathname. |
| 32 |
.P |
| 33 |
If the pathname does not start with the \[aq]/\[aq] character, the starting |
| 34 |
lookup directory of the resolution process is the current working directory of |
| 35 |
the process \[em] or in the case of |
| 36 |
.BR openat (2)-style |
| 37 |
system calls, the |
| 38 |
.I dfd |
| 39 |
argument (or the current working directory if |
| 40 |
.B AT_FDCWD |
| 41 |
is passed as the |
| 42 |
.I dfd |
| 43 |
argument). |
| 44 |
The current working directory is inherited from the parent, and can |
| 45 |
be changed by use of the |
| 46 |
.BR chdir (2) |
| 47 |
system call. |
| 48 |
.P |
| 49 |
Pathnames starting with a \[aq]/\[aq] character are called absolute pathnames. |
| 50 |
Pathnames not starting with a \[aq]/\[aq] are called relative pathnames. |
| 51 |
.SS Step 2: walk along the path |
| 52 |
Set the current lookup directory to the starting lookup directory. |
| 53 |
Now, for each nonfinal component of the pathname, where a component |
| 54 |
is a substring delimited by \[aq]/\[aq] characters, this component is looked up |
| 55 |
in the current lookup directory. |
| 56 |
.P |
| 57 |
If the process does not have search permission on |
| 58 |
the current lookup directory, |
| 59 |
an |
| 60 |
.B EACCES |
| 61 |
error is returned ("Permission denied"). |
| 62 |
.P |
| 63 |
If the component is not found, an |
| 64 |
.B ENOENT |
| 65 |
error is returned |
| 66 |
("No such file or directory"). |
| 67 |
.P |
| 68 |
If the component is found, but is neither a directory nor a symbolic link, |
| 69 |
an |
| 70 |
.B ENOTDIR |
| 71 |
error is returned ("Not a directory"). |
| 72 |
.P |
| 73 |
If the component is found and is a directory, we set the |
| 74 |
current lookup directory to that directory, and go to the |
| 75 |
next component. |
| 76 |
.P |
| 77 |
If the component is found and is a symbolic link, |
| 78 |
we first resolve this symbolic link |
| 79 |
(with the current lookup directory |
| 80 |
as starting lookup directory). |
| 81 |
Upon error, that error is returned. |
| 82 |
If the result is not a directory, an |
| 83 |
.B ENOTDIR |
| 84 |
error is returned. |
| 85 |
If the resolution of the symbolic link is successful and returns a directory, |
| 86 |
we set the current lookup directory to that directory, and go to |
| 87 |
the next component. |
| 88 |
Note that the resolution process here can involve recursion if the |
| 89 |
prefix ('dirname') component of a pathname contains a filename |
| 90 |
that is a symbolic link that resolves to a directory (where the |
| 91 |
prefix component of that directory may contain a symbolic link, and so on). |
| 92 |
In order to protect the kernel against stack overflow, and also |
| 93 |
to protect against denial of service, there are limits on the |
| 94 |
maximum recursion depth, and on the maximum number of symbolic links |
| 95 |
followed. |
| 96 |
An |
| 97 |
.B ELOOP |
| 98 |
error is returned when the maximum is |
| 99 |
exceeded ("Too many levels of symbolic links"). |
| 100 |
.P |
| 101 |
.\" |
| 102 |
.\" presently: max recursion depth during symlink resolution: 5 |
| 103 |
.\" max total number of symbolic links followed: 40 |
| 104 |
.\" _POSIX_SYMLOOP_MAX is 8 |
| 105 |
As currently implemented on Linux, the maximum number |
| 106 |
.\" MAXSYMLINKS is 40 |
| 107 |
of symbolic links that will be followed while resolving a pathname is 40. |
| 108 |
Before Linux 2.6.18, the limit on the recursion depth was 5. |
| 109 |
Starting with Linux 2.6.18, this limit |
| 110 |
.\" MAX_NESTED_LINKS |
| 111 |
was raised to 8. |
| 112 |
In Linux 4.2, |
| 113 |
.\" commit 894bc8c4662ba9daceafe943a5ba0dd407da5cd3 |
| 114 |
the kernel's pathname-resolution code |
| 115 |
was reworked to eliminate the use of recursion, |
| 116 |
so that the only limit that remains is the maximum of 40 |
| 117 |
resolutions for the entire pathname. |
| 118 |
.P |
| 119 |
The resolution of symbolic links during this stage can be blocked by using |
| 120 |
.BR openat2 (2), |
| 121 |
with the |
| 122 |
.B RESOLVE_NO_SYMLINKS |
| 123 |
flag set. |
| 124 |
.SS Step 3: find the final entry |
| 125 |
The lookup of the final component of the pathname goes just like |
| 126 |
that of all other components, as described in the previous step, |
| 127 |
with two differences: (i) the final component need not be a |
| 128 |
directory (at least as far as the path resolution process is |
| 129 |
concerned\[em]it may have to be a directory, or a nondirectory, because of |
| 130 |
the requirements of the specific system call), and (ii) it |
| 131 |
is not necessarily an error if the component is not found\[em]maybe |
| 132 |
we are just creating it. |
| 133 |
The details on the treatment |
| 134 |
of the final entry are described in the manual pages of the specific |
| 135 |
system calls. |
| 136 |
.SS "\&.\& and .." |
| 137 |
By convention, every directory has the entries "." and "..", |
| 138 |
which refer to the directory itself and to its parent directory, |
| 139 |
respectively. |
| 140 |
.P |
| 141 |
The path resolution process will assume that these entries have |
| 142 |
their conventional meanings, regardless of whether they are |
| 143 |
actually present in the physical filesystem. |
| 144 |
.P |
| 145 |
One cannot walk up past the root: "/.." is the same as "/". |
| 146 |
.SS Mount points |
| 147 |
After a |
| 148 |
.I mount dev path |
| 149 |
command, the pathname "path" refers to |
| 150 |
the root of the filesystem hierarchy on the device "dev", and no |
| 151 |
longer to whatever it referred to earlier. |
| 152 |
.P |
| 153 |
One can walk out of a mounted filesystem: "path/.." refers to |
| 154 |
the parent directory of "path", |
| 155 |
outside of the filesystem hierarchy on "dev". |
| 156 |
.P |
| 157 |
Traversal of mount points can be blocked by using |
| 158 |
.BR openat2 (2), |
| 159 |
with the |
| 160 |
.B RESOLVE_NO_XDEV |
| 161 |
flag set (though note that this also restricts bind mount traversal). |
| 162 |
.SS Trailing slashes |
| 163 |
If a pathname ends in a \[aq]/\[aq], that forces resolution of the preceding |
| 164 |
component as in Step 2: |
| 165 |
the component preceding the slash either exists and resolves to a directory |
| 166 |
or it names a directory that is to be created |
| 167 |
immediately after the pathname is resolved. |
| 168 |
Otherwise, a trailing \[aq]/\[aq] is ignored. |
| 169 |
.SS Final symbolic link |
| 170 |
If the last component of a pathname is a symbolic link, then it |
| 171 |
depends on the system call whether the file referred to will be |
| 172 |
the symbolic link or the result of path resolution on its contents. |
| 173 |
For example, the system call |
| 174 |
.BR lstat (2) |
| 175 |
will operate on the symbolic link, |
| 176 |
while |
| 177 |
.BR stat (2) |
| 178 |
operates on the file pointed to by the symbolic link. |
| 179 |
.SS Length limit |
| 180 |
There is a maximum length for pathnames. |
| 181 |
If the pathname (or some |
| 182 |
intermediate pathname obtained while resolving symbolic links) |
| 183 |
is too long, an |
| 184 |
.B ENAMETOOLONG |
| 185 |
error is returned ("Filename too long"). |
| 186 |
.SS Empty pathname |
| 187 |
In the original UNIX, the empty pathname referred to the current directory. |
| 188 |
Nowadays POSIX decrees that an empty pathname must not be resolved |
| 189 |
successfully. |
| 190 |
Linux returns |
| 191 |
.B ENOENT |
| 192 |
in this case. |
| 193 |
.SS Permissions |
| 194 |
The permission bits of a file consist of three groups of three bits; |
| 195 |
see |
| 196 |
.BR chmod (1) |
| 197 |
and |
| 198 |
.BR stat (2). |
| 199 |
The first group of three is used when the effective user ID of |
| 200 |
the calling process equals the owner ID of the file. |
| 201 |
The second group |
| 202 |
of three is used when the group ID of the file either equals the |
| 203 |
effective group ID of the calling process, or is one of the |
| 204 |
supplementary group IDs of the calling process (as set by |
| 205 |
.BR setgroups (2)). |
| 206 |
When neither holds, the third group is used. |
| 207 |
.P |
| 208 |
Of the three bits used, the first bit determines read permission, |
| 209 |
the second write permission, and the last execute permission |
| 210 |
in case of ordinary files, or search permission in case of directories. |
| 211 |
.P |
| 212 |
Linux uses the fsuid instead of the effective user ID in permission checks. |
| 213 |
Ordinarily the fsuid will equal the effective user ID, but the fsuid can be |
| 214 |
changed by the system call |
| 215 |
.BR setfsuid (2). |
| 216 |
.P |
| 217 |
(Here "fsuid" stands for something like "filesystem user ID". |
| 218 |
The concept was required for the implementation of a user space |
| 219 |
NFS server at a time when processes could send a signal to a process |
| 220 |
with the same effective user ID. |
| 221 |
It is obsolete now. |
| 222 |
Nobody should use |
| 223 |
.BR setfsuid (2).) |
| 224 |
.P |
| 225 |
Similarly, Linux uses the fsgid ("filesystem group ID") |
| 226 |
instead of the effective group ID. |
| 227 |
See |
| 228 |
.BR setfsgid (2). |
| 229 |
.\" FIXME . say something about filesystem mounted read-only ? |
| 230 |
.SS Bypassing permission checks: superuser and capabilities |
| 231 |
On a traditional UNIX system, the superuser |
| 232 |
.RI ( root , |
| 233 |
user ID 0) is all-powerful, and bypasses all permissions restrictions |
| 234 |
when accessing files. |
| 235 |
.\" (but for exec at least one x bit must be set) -- AEB |
| 236 |
.\" but there is variation across systems on this point: for |
| 237 |
.\" example, HP-UX and Tru64 are as described by AEB. However, |
| 238 |
.\" on some implementations (e.g., Solaris, FreeBSD), |
| 239 |
.\" access(X_OK) by superuser will report success, regardless |
| 240 |
.\" of the file's execute permission bits. -- MTK (Oct 05) |
| 241 |
.P |
| 242 |
On Linux, superuser privileges are divided into capabilities (see |
| 243 |
.BR capabilities (7)). |
| 244 |
Two capabilities are relevant for file permissions checks: |
| 245 |
.B CAP_DAC_OVERRIDE |
| 246 |
and |
| 247 |
.BR CAP_DAC_READ_SEARCH . |
| 248 |
(A process has these capabilities if its fsuid is 0.) |
| 249 |
.P |
| 250 |
The |
| 251 |
.B CAP_DAC_OVERRIDE |
| 252 |
capability overrides all permission checking, |
| 253 |
but grants execute permission only when at least one |
| 254 |
of the file's three execute permission bits is set. |
| 255 |
.P |
| 256 |
The |
| 257 |
.B CAP_DAC_READ_SEARCH |
| 258 |
capability grants read and search permission |
| 259 |
on directories, and read permission on ordinary files. |
| 260 |
.\" FIXME . say something about immutable files |
| 261 |
.\" FIXME . say something about ACLs |
| 262 |
.SH SEE ALSO |
| 263 |
.BR readlink (2), |
| 264 |
.BR capabilities (7), |
| 265 |
.BR credentials (7), |
| 266 |
.BR symlink (7) |