From 90879cbd20f563af6bcc0ee9035cd59f591c29c7 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Wed, 18 Aug 2021 03:02:55 +0200 Subject: [PATCH] chmod.2, chown.2, open.2, mkdir.2, mknod.2, readlink.2, stat.2, symlink.2, mkfifo.3, scandir.3, sem_wait.3: ERRORS: combine errors into a single alphabetic list These pages split out extra errors for some APIs into a separate list. Probably, the pages are easier to ready if all errors are combined into a single list. Note that there still remain a few pages where the errors are listed separately for different APIs. For the moment, it seems best to leave those pages as is, since the error lists are largely distinct in those pages. Signed-off-by: Michael Kerrisk --- man2/chmod.2 | 83 ++++++++++++++++++++----------------------------- man2/chown.2 | 75 ++++++++++++++++++-------------------------- man2/mkdir.2 | 33 ++++++++++---------- man2/mknod.2 | 33 ++++++++++---------- man2/open.2 | 33 ++++++++++---------- man2/readlink.2 | 21 ++++++------- man2/stat.2 | 42 ++++++++++++------------- man2/symlink.2 | 46 +++++++++++++-------------- man3/mkfifo.3 | 27 ++++++++-------- man3/scandir.3 | 21 ++++++------- man3/sem_wait.3 | 17 +++++----- 11 files changed, 196 insertions(+), 235 deletions(-) diff --git a/man2/chmod.2 b/man2/chmod.2 index 6862a7e3d..b1aa3691c 100644 --- a/man2/chmod.2 +++ b/man2/chmod.2 @@ -245,10 +245,30 @@ Search permission is denied on a component of the path prefix. (See also .BR path_resolution (7).) .TP +.B EBADF +.RB ( fchmod ()) +The file descriptor +.I fd +is not valid. +.TP +.B EBADF +.RB ( fchmodat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EFAULT .I pathname points outside your accessible address space. .TP +.B EINVAL +.RB ( fchmodat ()) +Invalid flag specified in +.IR flags . +.TP .B EIO An I/O error occurred. .TP @@ -269,6 +289,20 @@ Insufficient kernel memory was available. .B ENOTDIR A component of the path prefix is not a directory. .TP +.B ENOTDIR +.RB ( fchmodat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP +.B ENOTSUP +.RB ( fchmodat ()) +.I flags +specified +.BR AT_SYMLINK_NOFOLLOW , +which is not supported. +.TP .B EPERM The effective UID does not match the owner of the file, and the process is not privileged (Linux: it does not have the @@ -282,55 +316,6 @@ The file is marked immutable or append-only. .TP .B EROFS The named file resides on a read-only filesystem. -.PP -The general errors for -.BR fchmod () -are listed below: -.TP -.B EBADF -The file descriptor -.I fd -is not valid. -.TP -.B EIO -See above. -.TP -.B EPERM -See above. -.TP -.B EROFS -See above. -.PP -The same errors that occur for -.BR chmod () -can also occur for -.BR fchmodat (). -The following additional errors can occur for -.BR fchmodat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B EINVAL -Invalid flag specified in -.IR flags . -.TP -.B ENOTDIR -.I pathname -is relative and -.I dirfd -is a file descriptor referring to a file other than a directory. -.TP -.B ENOTSUP -.I flags -specified -.BR AT_SYMLINK_NOFOLLOW , -which is not supported. .SH VERSIONS .BR fchmodat () was added to Linux in kernel 2.6.16; diff --git a/man2/chown.2 b/man2/chown.2 index 354193c28..a3a76fda7 100644 --- a/man2/chown.2 +++ b/man2/chown.2 @@ -232,10 +232,33 @@ Search permission is denied on a component of the path prefix. (See also .BR path_resolution (7).) .TP +.B EBADF +.RB ( fchown ()) +.I fd +is not a valid open file descriptor. +.TP +.B EBADF +.RB ( fchownat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EFAULT .I pathname points outside your accessible address space. .TP +.B EINVAL +.RB ( fchownat ()) +Invalid flag specified in +.IR flags . +.TP +.B EIO +.RB ( fchown ()) +A low-level I/O error occurred while modifying the inode. +.TP .B ELOOP Too many symbolic links were encountered in resolving .IR pathname . @@ -253,6 +276,13 @@ Insufficient kernel memory was available. .B ENOTDIR A component of the path prefix is not a directory. .TP +.B ENOTDIR +.RB ( fchownat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP .B EPERM The calling process did not have the required permissions (see above) to change owner and/or group. @@ -264,51 +294,6 @@ The file is marked immutable or append-only. .TP .B EROFS The named file resides on a read-only filesystem. -.PP -The general errors for -.BR fchown () -are listed below: -.TP -.B EBADF -.I fd -is not a valid open file descriptor. -.TP -.B EIO -A low-level I/O error occurred while modifying the inode. -.TP -.B ENOENT -See above. -.TP -.B EPERM -See above. -.TP -.B EROFS -See above. -.PP -The same errors that occur for -.BR chown () -can also occur for -.BR fchownat (). -The following additional errors can occur for -.BR fchownat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B EINVAL -Invalid flag specified in -.IR flags . -.TP -.B ENOTDIR -.I pathname -is relative and -.I dirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR fchownat () was added to Linux in kernel 2.6.16; diff --git a/man2/mkdir.2 b/man2/mkdir.2 index 355ba086e..9c541058f 100644 --- a/man2/mkdir.2 +++ b/man2/mkdir.2 @@ -126,6 +126,15 @@ did not allow search permission. (See also .BR path_resolution (7).) .TP +.B EBADF +.RB ( mkdirat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EDQUOT The user's quota of disk blocks or inodes on the filesystem has been exhausted. @@ -179,6 +188,13 @@ A component used as a directory in .I pathname is not, in fact, a directory. .TP +.B ENOTDIR +.RB ( mkdirat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP .B EPERM The filesystem containing .I pathname @@ -187,23 +203,6 @@ does not support the creation of directories. .B EROFS .I pathname refers to a file on a read-only filesystem. -.PP -The following additional errors can occur for -.BR mkdirat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B ENOTDIR -.I pathname -is relative and -.I dirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR mkdirat () was added to Linux in kernel 2.6.16; diff --git a/man2/mknod.2 b/man2/mknod.2 index f5bb0900a..143f67d0a 100644 --- a/man2/mknod.2 +++ b/man2/mknod.2 @@ -163,6 +163,15 @@ did not allow search permission. (See also .BR path_resolution (7).) .TP +.B EBADF +.BR ( mknodat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EDQUOT The user's quota of disk blocks or inodes on the filesystem has been exhausted. @@ -207,6 +216,13 @@ A component used as a directory in .I pathname is not, in fact, a directory. .TP +.B ENOTDIR +.BR ( mknodat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP .B EPERM .I mode requested creation of something other than a regular file, @@ -224,23 +240,6 @@ does not support the type of node requested. .B EROFS .I pathname refers to a file on a read-only filesystem. -.PP -The following additional errors can occur for -.BR mknodat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B ENOTDIR -.I pathname -is relative and -.I dirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR mknodat () was added to Linux in kernel 2.6.16; diff --git a/man2/open.2 b/man2/open.2 index af8120cfa..5eca172ec 100644 --- a/man2/open.2 +++ b/man2/open.2 @@ -1034,6 +1034,15 @@ and in .BR proc (5). .TP +.B EBADF +.RB ( openat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EBUSY .B O_EXCL was specified in @@ -1210,6 +1219,13 @@ is not, in fact, a directory, or \fBO_DIRECTORY\fP was specified and .I pathname was not a directory. .TP +.B ENOTDIR +.RB ( openat ()) +.I pathname +is a relative pathname and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP .B ENXIO .BR O_NONBLOCK " | " O_WRONLY is set, the named file is a FIFO, and @@ -1285,23 +1301,6 @@ The flag was specified, and an incompatible lease was held on the file (see .BR fcntl (2)). -.PP -The following additional errors can occur for -.BR openat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B ENOTDIR -.I pathname -is a relative pathname and -.I dirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR openat () was added to Linux in kernel 2.6.16; diff --git a/man2/readlink.2 b/man2/readlink.2 index 6ae07c385..a1ffbf7d0 100644 --- a/man2/readlink.2 +++ b/man2/readlink.2 @@ -160,6 +160,15 @@ Search permission is denied for a component of the path prefix. (See also .BR path_resolution (7).) .TP +.B EBADF +.RB ( readlinkat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EFAULT .I buf extends outside the process's allocated address space. @@ -195,19 +204,9 @@ Insufficient kernel memory was available. .TP .B ENOTDIR A component of the path prefix is not a directory. -.PP -The following additional errors can occur for -.BR readlinkat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. .TP .B ENOTDIR +.RB ( readlinkat ()) .I pathname is relative and .I dirfd diff --git a/man2/stat.2 b/man2/stat.2 index e5859abaf..08a99690a 100644 --- a/man2/stat.2 +++ b/man2/stat.2 @@ -381,9 +381,23 @@ in the path prefix of .I fd is not a valid open file descriptor. .TP +.B EBADF +.RB ( fstatat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EFAULT Bad address. .TP +.B EINVAL +.RB ( fstatat ()) +Invalid flag specified in +.IR flags . +.TP .B ELOOP Too many symbolic links encountered while traversing the path. .TP @@ -411,6 +425,13 @@ A component of the path prefix of .I pathname is not a directory. .TP +.B ENOTDIR +.RB ( fstatat ()) +.I pathname +is relative and +.I dirfd +is a file descriptor referring to a file other than a directory. +.TP .B EOVERFLOW .I pathname or @@ -429,27 +450,6 @@ calls on a file whose size exceeds .I (1<<31)\-1 bytes. -.PP -The following additional errors can occur for -.BR fstatat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B EINVAL -Invalid flag specified in -.IR flags . -.TP -.B ENOTDIR -.I pathname -is relative and -.I dirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR fstatat () was added to Linux in kernel 2.6.16; diff --git a/man2/symlink.2 b/man2/symlink.2 index f0c4293a7..f5bf7ef23 100644 --- a/man2/symlink.2 +++ b/man2/symlink.2 @@ -152,6 +152,15 @@ did not allow search permission. (See also .BR path_resolution (7).) .TP +.B EBADF +.RB ( symlinkat ()) +.I linkpath +is relative but +.I newdirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EDQUOT The user's quota of resources on the filesystem has been exhausted. The resources could be inodes or disk blocks, depending on the filesystem @@ -183,6 +192,13 @@ or .I linkpath is an empty string. .TP +.B ENOENT +.RB ( symlinkat ()) +.I linkpath +is a relative pathname and +.IR newdirfd +refers to a directory that has been deleted. +.TP .B ENOMEM Insufficient kernel memory was available. .TP @@ -195,6 +211,13 @@ A component used as a directory in .I linkpath is not, in fact, a directory. .TP +.B ENOTDIR +.RB ( symlinkat ()) +.I linkpath +is relative and +.I newdirfd +is a file descriptor referring to a file other than a directory. +.TP .B EPERM The filesystem containing .I linkpath @@ -203,29 +226,6 @@ does not support the creation of symbolic links. .B EROFS .I linkpath is on a read-only filesystem. -.PP -The following additional errors can occur for -.BR symlinkat (): -.TP -.B EBADF -.I linkpath -is relative but -.I newdirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP -.B ENOENT -.I linkpath -is a relative pathname and -.IR newdirfd -refers to a directory that has been deleted. -.TP -.B ENOTDIR -.I linkpath -is relative and -.I newdirfd -is a file descriptor referring to a file other than a directory. .SH VERSIONS .BR symlinkat () was added to Linux in kernel 2.6.16; diff --git a/man3/mkfifo.3 b/man3/mkfifo.3 index 3aba5498c..a0c578939 100644 --- a/man3/mkfifo.3 +++ b/man3/mkfifo.3 @@ -131,6 +131,15 @@ is set to indicate the error. One of the directories in \fIpathname\fP did not allow search (execute) permission. .TP +.B EBADF +.RB ( mkfifoat ()) +.I pathname +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B EDQUOT The user's quota of disk blocks or inodes on the filesystem has been exhausted. @@ -160,25 +169,15 @@ The directory or filesystem has no room for the new file. A component used as a directory in \fIpathname\fP is not, in fact, a directory. .TP -.B EROFS -\fIpathname\fP refers to a read-only filesystem. -.PP -The following additional errors can occur for -.BR mkfifoat (): -.TP -.B EBADF -.I pathname -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. -.TP .B ENOTDIR +.RB ( mkfifoat ()) .I pathname is a relative pathname and .I dirfd is a file descriptor referring to a file other than a directory. +.TP +.B EROFS +\fIpathname\fP refers to a read-only filesystem. .SH VERSIONS .BR mkfifoat () was added to glibc in version 2.4. diff --git a/man3/scandir.3 b/man3/scandir.3 index f3a34db53..f01072067 100644 --- a/man3/scandir.3 +++ b/man3/scandir.3 @@ -191,6 +191,15 @@ or greater than zero if the first argument is considered to be respectively less than, equal to, or greater than the second. .SH ERRORS .TP +.B EBADF +.RB ( scandirat ()) +.I dirp +is relative but +.I dirfd +is neither +.B AT_FDCWD +nor a valid file descriptor. +.TP .B ENOENT The path in \fIdirp\fR does not exist. .TP @@ -199,19 +208,9 @@ Insufficient memory to complete the operation. .TP .B ENOTDIR The path in \fIdirp\fR is not a directory. -.PP -The following additional errors can occur for -.BR scandirat (): -.TP -.B EBADF -.I dirp -is relative but -.I dirfd -is neither -.B AT_FDCWD -nor a valid file descriptor. .TP .B ENOTDIR +.RB ( scandirat ()) .I dirp is a relative pathname and .I dirfd diff --git a/man3/sem_wait.3 b/man3/sem_wait.3 index bb86d984b..40cedb2a3 100644 --- a/man3/sem_wait.3 +++ b/man3/sem_wait.3 @@ -113,6 +113,11 @@ on error, the value of the semaphore is left unchanged, is set to indicate the error. .SH ERRORS .TP +.B EAGAIN +.RB ( sem_trywait ()) +The operation could not be performed without blocking (i.e., the +semaphore currently has the value zero). +.TP .B EINTR The call was interrupted by a signal handler; see .BR signal (7). @@ -120,23 +125,15 @@ The call was interrupted by a signal handler; see .B EINVAL .I sem is not a valid semaphore. -.PP -The following additional error can occur for -.BR sem_trywait (): -.TP -.B EAGAIN -The operation could not be performed without blocking (i.e., the -semaphore currently has the value zero). -.PP -The following additional errors can occur for -.BR sem_timedwait (): .TP .B EINVAL +.RB ( sem_timedwait ()) The value of .I abs_timeout.tv_nsecs is less than 0, or greater than or equal to 1000 million. .TP .B ETIMEDOUT +.RB ( sem_timedwait ()) The call timed out before the semaphore could be locked. .\" POSIX.1-2001 also allows EDEADLK -- "A deadlock condition .\" was detected", but this does not occur on Linux(?).