1PATH_RESOLUTION(7)         Linux Programmer's Manual        PATH_RESOLUTION(7)
2
3
4

NAME

6       path_resolution - how a pathname is resolved to a file
7

DESCRIPTION

9       Some  UNIX/Linux  system calls have as parameter one or more filenames.
10       A filename (or pathname) is resolved as follows.
11
12   Step 1: start of the resolution process
13       If the pathname starts with the  '/'  character,  the  starting  lookup
14       directory  is  the  root  directory of the calling process.  (A process
15       inherits its root directory from its parent.  Usually this will be  the
16       root  directory  of  the file hierarchy.  A process may get a different
17       root directory by use of the chroot(2) system call.  A process may  get
18       an entirely private mount namespace in case it—or one of its ancestors—
19       was started by an invocation of the clone(2) system call that  had  the
20       CLONE_NEWNS flag set.)  This handles the '/' part of the pathname.
21
22       If  the  pathname  does  not start with the '/' character, the starting
23       lookup directory of the  resolution  process  is  the  current  working
24       directory of the process.  (This is also inherited from the parent.  It
25       can be changed by use of the chdir(2) system call.)
26
27       Pathnames starting with a '/' character are called absolute  pathnames.
28       Pathnames not starting with a '/' are called relative pathnames.
29
30   Step 2: walk along the path
31       Set  the  current  lookup  directory  to the starting lookup directory.
32       Now, for each nonfinal component of the pathname, where a component  is
33       a substring delimited by '/' characters, this component is looked up in
34       the current lookup directory.
35
36       If the process does not have search permission on  the  current  lookup
37       directory, an EACCES error is returned ("Permission denied").
38
39       If  the  component  is not found, an ENOENT error is returned ("No such
40       file or directory").
41
42       If the component is found, but is neither a directory  nor  a  symbolic
43       link, an ENOTDIR error is returned ("Not a directory").
44
45       If the component is found and is a directory, we set the current lookup
46       directory to that directory, and go to the next component.
47
48       If the component is found and is a symbolic link  (symlink),  we  first
49       resolve this symbolic link (with the current lookup directory as start‐
50       ing lookup directory).  Upon error, that error  is  returned.   If  the
51       result  is not a directory, an ENOTDIR error is returned.  If the reso‐
52       lution of the symlink is successful and returns a directory, we set the
53       current  lookup  directory to that directory, and go to the next compo‐
54       nent.  Note that the resolution process here can involve  recursion  if
55       the prefix ('dirname') component of a pathname contains a filename that
56       is a symbolic link that resolves to a directory (where the prefix  com‐
57       ponent  of  that directory may contain a symbolic link, and so on).  In
58       order to protect the kernel against stack overflow, and also to protect
59       against  denial  of  service, there are limits on the maximum recursion
60       depth, and on the maximum number of symbolic links followed.  An  ELOOP
61       error  is  returned  when  the maximum is exceeded ("Too many levels of
62       symbolic links").
63
64       As currently implemented on Linux, the maximum number of symbolic links
65       that  will  be  followed  while resolving a pathname is 40.  In kernels
66       before 2.6.18, the limit on the recursion depth was 5.   Starting  with
67       Linux  2.6.18,  this limit was raised to 8.  In Linux 4.2, the kernel's
68       pathname-resolution code was reworked to eliminate the  use  of  recur‐
69       sion,  so that the only limit that remains is the maximum of 40 resolu‐
70       tions for the entire pathname.
71
72   Step 3: find the final entry
73       The lookup of the final component of the pathname goes just  like  that
74       of  all  other  components, as described in the previous step, with two
75       differences: (i) the final component need not be a directory (at  least
76       as  far as the path resolution process is concerned—it may have to be a
77       directory, or a nondirectory, because of the requirements of  the  spe‐
78       cific system call), and (ii) it is not necessarily an error if the com‐
79       ponent is not found—maybe we are just creating it.  The details on  the
80       treatment  of  the final entry are described in the manual pages of the
81       specific system calls.
82
83   . and ..
84       By convention, every directory has the  entries  "."  and  "..",  which
85       refer  to  the  directory  itself  and to its parent directory, respec‐
86       tively.
87
88       The path resolution process will assume that these entries  have  their
89       conventional  meanings, regardless of whether they are actually present
90       in the physical filesystem.
91
92       One cannot walk down past the root: "/.." is the same as "/".
93
94   Mount points
95       After a "mount dev path" command, the pathname  "path"  refers  to  the
96       root  of the filesystem hierarchy on the device "dev", and no longer to
97       whatever it referred to earlier.
98
99       One can walk out of a mounted filesystem: "path/.." refers to the  par‐
100       ent directory of "path", outside of the filesystem hierarchy on "dev".
101
102   Trailing slashes
103       If  a  pathname  ends in a '/', that forces resolution of the preceding
104       component as in Step 2: it has to exist and  resolve  to  a  directory.
105       Otherwise,  a  trailing  '/' is ignored.  (Or, equivalently, a pathname
106       with a trailing '/' is equivalent to the pathname obtained by appending
107       '.' to it.)
108
109   Final symlink
110       If the last component of a pathname is a symbolic link, then it depends
111       on the system call whether the file referred to will  be  the  symbolic
112       link  or  the  result of path resolution on its contents.  For example,
113       the system call lstat(2) will operate on  the  symlink,  while  stat(2)
114       operates on the file pointed to by the symlink.
115
116   Length limit
117       There  is  a  maximum  length  for pathnames.  If the pathname (or some
118       intermediate pathname obtained while resolving symbolic links)  is  too
119       long, an ENAMETOOLONG error is returned ("Filename too long").
120
121   Empty pathname
122       In the original UNIX, the empty pathname referred to the current direc‐
123       tory.  Nowadays POSIX decrees  that  an  empty  pathname  must  not  be
124       resolved successfully.  Linux returns ENOENT in this case.
125
126   Permissions
127       The  permission  bits  of a file consist of three groups of three bits;
128       see chmod(1) and stat(2).  The first group of three is  used  when  the
129       effective  user  ID  of  the calling process equals the owner ID of the
130       file.  The second group of three is used when the group ID of the  file
131       either  equals the effective group ID of the calling process, or is one
132       of the supplementary group IDs of the calling process (as set  by  set‐
133       groups(2)).  When neither holds, the third group is used.
134
135       Of  the  three bits used, the first bit determines read permission, the
136       second write permission, and the last execute  permission  in  case  of
137       ordinary files, or search permission in case of directories.
138
139       Linux  uses  the  fsuid  instead of the effective user ID in permission
140       checks.  Ordinarily the fsuid will equal the effective user ID, but the
141       fsuid can be changed by the system call setfsuid(2).
142
143       (Here "fsuid" stands for something like "filesystem user ID".  The con‐
144       cept was required for the implementation of a user space NFS server  at
145       a  time  when  processes could send a signal to a process with the same
146       effective user ID.  It  is  obsolete  now.   Nobody  should  use  setf‐
147       suid(2).)
148
149       Similarly,  Linux uses the fsgid ("filesystem group ID") instead of the
150       effective group ID.  See setfsgid(2).
151
152   Bypassing permission checks: superuser and capabilities
153       On a traditional UNIX system, the superuser (root, user ID 0)  is  all-
154       powerful,  and  bypasses  all  permissions  restrictions when accessing
155       files.
156
157       On Linux, superuser privileges are divided into capabilities (see capa‐
158       bilities(7)).   Two  capabilities  are  relevant  for  file permissions
159       checks: CAP_DAC_OVERRIDE and CAP_DAC_READ_SEARCH.  (A process has these
160       capabilities if its fsuid is 0.)
161
162       The  CAP_DAC_OVERRIDE capability overrides all permission checking, but
163       grants execute permission only when at least one of  the  file's  three
164       execute permission bits is set.
165
166       The CAP_DAC_READ_SEARCH capability grants read and search permission on
167       directories, and read permission on ordinary files.
168

SEE ALSO

170       readlink(2), capabilities(7), credentials(7), symlink(7)
171

COLOPHON

173       This page is part of release 4.16 of the Linux  man-pages  project.   A
174       description  of  the project, information about reporting bugs, and the
175       latest    version    of    this    page,    can     be     found     at
176       https://www.kernel.org/doc/man-pages/.
177
178
179
180Linux                             2017-11-26                PATH_RESOLUTION(7)
Impressum