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