diff options
Diffstat (limited to 'man2/path_resolution.2')
| -rw-r--r-- | man2/path_resolution.2 | 212 |
1 files changed, 212 insertions, 0 deletions
diff --git a/man2/path_resolution.2 b/man2/path_resolution.2 new file mode 100644 index 000000000..ec6dcd3de --- /dev/null +++ b/man2/path_resolution.2 @@ -0,0 +1,212 @@ +.\" Copyright (C) 2003 Andries Brouwer (aeb@cwi.nl) +.\" +.\" 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. +.\" +.TH PATH_RESOLUTION 2 2004-06-21 "Linux 2.6.7" "Linux Programmer's Manual" +.SH NAME +Unix/Linux path resolution \- find the file referred to by a filename +.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 '/' 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 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 namespace in case +it - or one of its ancestors - was started by an invocation of the +.BR 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 +.BR chdir (2) +system call.) + +Pathnames starting with a '/' character are called absolute pathnames. +Pathnames not starting with a '/' are called relative pathnames. + +.SS "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 the current lookup directory. + +If the process does not have search permission on the current lookup directory, +an EACCES error is returned ("Permission denied"). + +If the component is not found, an ENOENT error is returned +("No such file or directory"). + +If the component is found, but is neither a directory nor a symbolic link, +an ENOTDIR error is returned ("Not a directory"). + +If the component is found and is a directory, we set the +current lookup directory to that directory, and go to the +next component. + +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 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 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 is returned when the maximum is +exceeded ("Too many levels of symbolic links"). +.\" +.\" presently: max recursion depth during symlink resolution: 5 +.\" max total number of symlinks followed: 40 +.\" _POSIX_SYMLOOP_MAX is 8 + +.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 - +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 if the component is not found - +maybe 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. + +The path resolution process will assume that these entries have +their conventional meanings, regardless of whether they are +actually present in the physical filesystem. + +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. + +One can walk out of a mounted filesystem: "path/.." refers to +the parent directy of "path", outside of the filesystem hierarchy on "dev". + +.SS "Trailing slashes" +If a pathname ends in a '/', that forces resolution of the preceding +component as in 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.) + +.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 ENAMETOOLONG error is returned ("File name 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 ENOENT in this case. + +.SS "Permissions" +The permission bits of a file consist of three groups of three bits, cf.\& +.BR chmod (1) +and +.BR stat (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 either equals the +effective group ID of the current process, or is one of the +supplementary group IDs of the current process (as set by +.BR setgroups (2)). +When neither holds, the third group is used. + +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. + +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). + +(Here "fsuid" stands for something like "file system 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).) + +Similarly, Linux uses the fsgid instead of the effective group ID. See +.BR setfsgid (2). + +.\" say sth on fs mounted read-only ? + +.SS "Capabilities" +If the permission bits of the file 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 time +a process gets all capabilities except CAP_SETPCAP and the five capabilities +CAP_CHOWN, CAP_DAC_OVERRIDE, CAP_DAC_READ_SEARCH, CAP_FOWNER, CAP_FSETID, +in case it has zero euid, and it gets these last five capabilities +in 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 execute permission bits is set. + +The CAP_DAC_READ_SEARCH capability will grant read and search permission +on directories, and read permission on ordinary files. + +.\" Is there a better place for this? +The CAP_SYS_ADMIN capability will (e.g.) allow a process to violate +the limit (visible in +.IR /proc/sys/fs/file-max ) +on the maximum number of open files in the system, where a process +lacking that capability would see an ENFILE error return. + +.\" say sth on immutable files + +.\" say sth on ACLs + +.SH "SEE ALSO" +.BR capabilities (7) |