From 855d489a7f90cfeaae45c55f80a65dc2135aaa75 Mon Sep 17 00:00:00 2001 From: Michael Kerrisk Date: Thu, 7 Jan 2021 07:50:50 +0100 Subject: [PATCH] Various pages: Standardize wording around setting of 'errno' on error In the RETURN VALUE sections, a number of different wordings are used in to describe the fact that 'errno' is set on error. There's no reason for the difference in wordings, since the same thing is being described in each case. Switch to a standard wording that is the same as FreeBSD and similar to the wording used in POSIX.1. In this change, "to indicate the cause of the error" is changed to "to indicate the error". Signed-off-by: Michael Kerrisk --- man2/add_key.2 | 2 +- man2/futex.2 | 2 +- man2/getpriority.2 | 2 +- man2/inotify_rm_watch.2 | 2 +- man2/ioctl_userfaultfd.2 | 12 ++++++------ man2/mmap.2 | 4 ++-- man2/open_by_handle_at.2 | 2 +- man2/perfmonctl.2 | 2 +- man2/pidfd_getfd.2 | 2 +- man2/pidfd_open.2 | 2 +- man2/pidfd_send_signal.2 | 2 +- man2/poll.2 | 2 +- man2/pread.2 | 2 +- man2/readahead.2 | 2 +- man2/request_key.2 | 2 +- man2/sched_setattr.2 | 2 +- man2/seccomp.2 | 2 +- man2/shmop.2 | 4 ++-- man2/sysinfo.2 | 2 +- man2/write.2 | 2 +- man3/bindresvport.3 | 2 +- man3/ctime.3 | 2 +- man3/dirfd.3 | 2 +- man3/duplocale.3 | 2 +- man3/fpathconf.3 | 2 +- man3/get_phys_pages.3 | 2 +- man3/getlogin.3 | 2 +- man3/getspnam.3 | 2 +- man3/hsearch.3 | 4 ++-- man3/inet_net_pton.3 | 4 ++-- man3/newlocale.3 | 2 +- man3/posix_memalign.3 | 2 +- man3/pthread_mutex_consistent.3 | 2 +- man3/random.3 | 2 +- man3/random_r.3 | 2 +- man3/scandir.3 | 2 +- man3/setenv.3 | 2 +- man3/shm_open.3 | 2 +- man3/siginterrupt.3 | 2 +- man3/sigsetops.3 | 2 +- man3/strdup.3 | 2 +- man3/sysconf.3 | 2 +- man3/tempnam.3 | 2 +- man3/timegm.3 | 2 +- man3/uselocale.3 | 2 +- man3/usleep.3 | 2 +- man3/wcsdup.3 | 2 +- 47 files changed, 56 insertions(+), 56 deletions(-) diff --git a/man2/add_key.2 b/man2/add_key.2 index 0d136e4aa..3b41580a2 100644 --- a/man2/add_key.2 +++ b/man2/add_key.2 @@ -147,7 +147,7 @@ On success, returns the serial number of the key it created or updated. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EACCES diff --git a/man2/futex.2 b/man2/futex.2 index 04df4896f..5f41abaa0 100644 --- a/man2/futex.2 +++ b/man2/futex.2 @@ -1320,7 +1320,7 @@ was invoked via .BR syscall (2)), all operations return \-1 and set .I errno -to indicate the cause of the error. +to indicate the error. .PP The return value on success depends on the operation, as described in the following list: diff --git a/man2/getpriority.2 b/man2/getpriority.2 index 4646ca533..e3fbeb4f3 100644 --- a/man2/getpriority.2 +++ b/man2/getpriority.2 @@ -123,7 +123,7 @@ On success, returns the calling thread's nice value, which may be a negative number. On error, it returns \-1 and sets .I errno -to indicate the cause of the error. +to indicate the error. .PP Since a successful call to .BR getpriority () diff --git a/man2/inotify_rm_watch.2 b/man2/inotify_rm_watch.2 index eae66d59d..459642ebc 100644 --- a/man2/inotify_rm_watch.2 +++ b/man2/inotify_rm_watch.2 @@ -53,7 +53,7 @@ On success, returns zero. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EBADF diff --git a/man2/ioctl_userfaultfd.2 b/man2/ioctl_userfaultfd.2 index 14dba4243..945badf08 100644 --- a/man2/ioctl_userfaultfd.2 +++ b/man2/ioctl_userfaultfd.2 @@ -235,7 +235,7 @@ This operation returns 0 on success. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .TP .B EFAULT @@ -333,7 +333,7 @@ This operation returns 0 on success. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .\" FIXME Is the following error list correct? .\" @@ -386,7 +386,7 @@ This operation returns 0 on success. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .TP .B EINVAL @@ -466,7 +466,7 @@ operation returns 0 on success. In this case, the entire area was copied. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .TP .B EAGAIN @@ -570,7 +570,7 @@ operation returns 0 on success. In this case, the entire area was zeroed. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .TP .B EAGAIN @@ -636,7 +636,7 @@ This operation returns 0 on success. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. Possible errors include: .TP .B EINVAL diff --git a/man2/mmap.2 b/man2/mmap.2 index 30170fbed..b44a8f1b7 100644 --- a/man2/mmap.2 +++ b/man2/mmap.2 @@ -497,14 +497,14 @@ On error, the value .IR "(void\ *)\ \-1" ) is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .PP On success, .BR munmap () returns 0. On failure, it returns \-1, and .I errno -is set to indicate the cause of the error (probably to +is set to indicate the error (probably to .BR EINVAL ). .SH ERRORS .TP diff --git a/man2/open_by_handle_at.2 b/man2/open_by_handle_at.2 index 56228a1ae..eb2ef1459 100644 --- a/man2/open_by_handle_at.2 +++ b/man2/open_by_handle_at.2 @@ -282,7 +282,7 @@ returns a file descriptor (a nonnegative integer). .PP In the event of an error, both system calls return \-1 and set .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .BR name_to_handle_at () and diff --git a/man2/perfmonctl.2 b/man2/perfmonctl.2 index 8c010069d..1c0197190 100644 --- a/man2/perfmonctl.2 +++ b/man2/perfmonctl.2 @@ -193,7 +193,7 @@ Reset PMC registers to default values. returns zero when the operation is successful. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH VERSIONS .BR perfmonctl () is available since Linux 2.4. diff --git a/man2/pidfd_getfd.2 b/man2/pidfd_getfd.2 index 1a1319aae..636aa46cb 100644 --- a/man2/pidfd_getfd.2 +++ b/man2/pidfd_getfd.2 @@ -74,7 +74,7 @@ On success, returns a file descriptor (a nonnegative integer). On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EBADF diff --git a/man2/pidfd_open.2 b/man2/pidfd_open.2 index b6a321562..51418d3db 100644 --- a/man2/pidfd_open.2 +++ b/man2/pidfd_open.2 @@ -53,7 +53,7 @@ On success, returns a file descriptor (a nonnegative integer). On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man2/pidfd_send_signal.2 b/man2/pidfd_send_signal.2 index da10c7d0f..02b8fac4b 100644 --- a/man2/pidfd_send_signal.2 +++ b/man2/pidfd_send_signal.2 @@ -96,7 +96,7 @@ On success, returns 0. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EBADF diff --git a/man2/poll.2 b/man2/poll.2 index b45e37f8a..f32051522 100644 --- a/man2/poll.2 +++ b/man2/poll.2 @@ -354,7 +354,7 @@ before any file descriptors became read. .PP On error, \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EFAULT diff --git a/man2/pread.2 b/man2/pread.2 index 9f2cabaa7..020467142 100644 --- a/man2/pread.2 +++ b/man2/pread.2 @@ -89,7 +89,7 @@ and .PP On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .BR pread () can fail and set diff --git a/man2/readahead.2 b/man2/readahead.2 index c551d8771..4f606770e 100644 --- a/man2/readahead.2 +++ b/man2/readahead.2 @@ -68,7 +68,7 @@ On success, .BR readahead () returns 0; on failure, \-1 is returned, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EBADF diff --git a/man2/request_key.2 b/man2/request_key.2 index 997c221b7..89bde01c3 100644 --- a/man2/request_key.2 +++ b/man2/request_key.2 @@ -378,7 +378,7 @@ On success, returns the serial number of the key it found or caused to be created. On error, \-1 is returned and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EACCES diff --git a/man2/sched_setattr.2 b/man2/sched_setattr.2 index 3d255f622..ecbdbffc4 100644 --- a/man2/sched_setattr.2 +++ b/man2/sched_setattr.2 @@ -303,7 +303,7 @@ and return 0. On error, \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .BR sched_getattr () and diff --git a/man2/seccomp.2 b/man2/seccomp.2 index 181e89bfc..cd1256a19 100644 --- a/man2/seccomp.2 +++ b/man2/seccomp.2 @@ -727,7 +727,7 @@ and .BR gettid (2).) On other errors, \-1 is returned, and .IR errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .BR seccomp () can fail for the following reasons: diff --git a/man2/shmop.2 b/man2/shmop.2 index 111f2f403..941ea6686 100644 --- a/man2/shmop.2 +++ b/man2/shmop.2 @@ -170,13 +170,13 @@ returns the address of the attached shared memory segment; on error, .I (void\ *)\ \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .PP On success, .BR shmdt () returns 0; on error \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS When .BR shmat () diff --git a/man2/sysinfo.2 b/man2/sysinfo.2 index ab58dae88..eedf0755f 100644 --- a/man2/sysinfo.2 +++ b/man2/sysinfo.2 @@ -104,7 +104,7 @@ On success, returns zero. On error, \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EFAULT diff --git a/man2/write.2 b/man2/write.2 index 37b251d9f..b6c42df8a 100644 --- a/man2/write.2 +++ b/man2/write.2 @@ -98,7 +98,7 @@ see NOTES for the upper limit on Linux. .SH RETURN VALUE On success, the number of bytes written is returned. On error, \-1 is returned, and \fIerrno\fP is set -to indicate the cause of the error. +to indicate the error. .PP Note that a successful .BR write () diff --git a/man3/bindresvport.3 b/man3/bindresvport.3 index 9bcecd047..805a784cd 100644 --- a/man3/bindresvport.3 +++ b/man3/bindresvport.3 @@ -70,7 +70,7 @@ has no way to return the port number actually allocated. .BR bindresvport () returns 0 on success; otherwise \-1 is returned and .I errno -set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .BR bindresvport () can fail for any of the same reasons as diff --git a/man3/ctime.3 b/man3/ctime.3 index b06640a61..3aeb1c692 100644 --- a/man3/ctime.3 +++ b/man3/ctime.3 @@ -311,7 +311,7 @@ returns the value The remaining functions return NULL on error. On error, .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EOVERFLOW diff --git a/man3/dirfd.3 b/man3/dirfd.3 index e38831ba0..7a9ad353f 100644 --- a/man3/dirfd.3 +++ b/man3/dirfd.3 @@ -64,7 +64,7 @@ On success, returns a file descriptor (a nonnegative integer). On error, \-1 is returned, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS POSIX.1-2008 specifies two errors, neither of which is returned by the current diff --git a/man3/duplocale.3 b/man3/duplocale.3 index 751ab5bf5..bf473c28a 100644 --- a/man3/duplocale.3 +++ b/man3/duplocale.3 @@ -66,7 +66,7 @@ On error, it returns .IR "(locale_t)\ 0", and sets .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B ENOMEM diff --git a/man3/fpathconf.3 b/man3/fpathconf.3 index 7cca6f256..e51d0643c 100644 --- a/man3/fpathconf.3 +++ b/man3/fpathconf.3 @@ -176,7 +176,7 @@ The return value of these functions is one of the following: .IP * 3 On error, \-1 is returned and .I errno -is set to indicate the cause of the error +is set to indicate the error (for example, .BR EINVAL , indicating that diff --git a/man3/get_phys_pages.3 b/man3/get_phys_pages.3 index 72bdae72c..55935128f 100644 --- a/man3/get_phys_pages.3 +++ b/man3/get_phys_pages.3 @@ -47,7 +47,7 @@ On success, these functions return a nonnegative value as given in DESCRIPTION. On failure, they return \-1 and set .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B ENOSYS diff --git a/man3/getlogin.3 b/man3/getlogin.3 index cebb2232d..f3d4e01a2 100644 --- a/man3/getlogin.3 +++ b/man3/getlogin.3 @@ -107,7 +107,7 @@ precisely because the user can set \fBLOGNAME\fP arbitrarily. returns a pointer to the username when successful, and NULL on failure, with .I errno -set to indicate the cause of the error. +set to indicate the error. .BR getlogin_r () returns 0 when successful, and nonzero on failure. .SH ERRORS diff --git a/man3/getspnam.3 b/man3/getspnam.3 index d7d781c76..a92627fc4 100644 --- a/man3/getspnam.3 +++ b/man3/getspnam.3 @@ -208,7 +208,7 @@ are available or if an error occurs during processing. The functions which have \fIint\fP as the return value return 0 for success and \-1 for failure, with .I errno -set to indicate the cause of the error. +set to indicate the error. .PP For the nonreentrant functions, the return value may point to static area, and may be overwritten by subsequent calls to these functions. diff --git a/man3/hsearch.3 b/man3/hsearch.3 index a4d1a6422..a2b00af21 100644 --- a/man3/hsearch.3 +++ b/man3/hsearch.3 @@ -175,7 +175,7 @@ and return nonzero on success. They return 0 on error, with .I errno -set to indicate the cause of the error. +set to indicate the error. .PP On success, .BR hsearch () @@ -189,7 +189,7 @@ cannot be found in the hash table. returns nonzero on success, and 0 on error. In the event of an error, these two functions set .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .BR hcreate_r () and diff --git a/man3/inet_net_pton.3 b/man3/inet_net_pton.3 index 94329ff8b..4c16ea6fe 100644 --- a/man3/inet_net_pton.3 +++ b/man3/inet_net_pton.3 @@ -125,7 +125,7 @@ On success, returns the number of bits in the network number. On error, it returns \-1, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .PP On success, .BR inet_net_ntop () @@ -133,7 +133,7 @@ returns .IR pres . On error, it returns NULL, and .I errno -is set to indicate the cause of the error. +is set to indicate the error. .SH ERRORS .TP .B EAFNOSUPPORT diff --git a/man3/newlocale.3 b/man3/newlocale.3 index 82f651911..d95c14ba9 100644 --- a/man3/newlocale.3 +++ b/man3/newlocale.3 @@ -181,7 +181,7 @@ returns .IR "(locale_t)\ 0", and sets .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/posix_memalign.3 b/man3/posix_memalign.3 index a7d5d185b..d063f8932 100644 --- a/man3/posix_memalign.3 +++ b/man3/posix_memalign.3 @@ -135,7 +135,7 @@ and .BR pvalloc () return a pointer to the allocated memory on success. On error, NULL is returned, and \fIerrno\fP is set -to indicate the cause of the error. +to indicate the error. .PP .BR posix_memalign () returns zero on success, or one of the error values listed in the diff --git a/man3/pthread_mutex_consistent.3 b/man3/pthread_mutex_consistent.3 index 2e56e44e0..13a216312 100644 --- a/man3/pthread_mutex_consistent.3 +++ b/man3/pthread_mutex_consistent.3 @@ -58,7 +58,7 @@ On success, .IR pthread_mutex_consistent () returns 0. Otherwise, -it returns a positive error number to indicate the cause of the error. +it returns a positive error number to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/random.3 b/man3/random.3 index d77a9b200..639e9a18c 100644 --- a/man3/random.3 +++ b/man3/random.3 @@ -138,7 +138,7 @@ On success, returns a pointer to the previous state array. On error, it returns NULL, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/random_r.3 b/man3/random_r.3 index 7be96e59d..5363e5e78 100644 --- a/man3/random_r.3 +++ b/man3/random_r.3 @@ -127,7 +127,7 @@ or be the result of a previous call of All of these functions return 0 on success. On error, \-1 is returned, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/scandir.3 b/man3/scandir.3 index 8a11720d5..328c70f69 100644 --- a/man3/scandir.3 +++ b/man3/scandir.3 @@ -178,7 +178,7 @@ function returns the number of directory entries selected. On error, \-1 is returned, with .I errno -set to indicate the cause of the error. +set to indicate the error. .PP The .BR alphasort () diff --git a/man3/setenv.3 b/man3/setenv.3 index 40f15d1e4..2d61cda6d 100644 --- a/man3/setenv.3 +++ b/man3/setenv.3 @@ -107,7 +107,7 @@ and functions return zero on success, or \-1 on error, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/shm_open.3 b/man3/shm_open.3 index 7f18dc158..580e03cf6 100644 --- a/man3/shm_open.3 +++ b/man3/shm_open.3 @@ -178,7 +178,7 @@ returns 0 on success, or \-1 on error. .SH ERRORS On failure, .I errno -is set to indicate the cause of the error. +is set to indicate the error. Values which may appear in .I errno include the following: diff --git a/man3/siginterrupt.3 b/man3/siginterrupt.3 index 79b7c153b..bd4bb3661 100644 --- a/man3/siginterrupt.3 +++ b/man3/siginterrupt.3 @@ -77,7 +77,7 @@ signal number .I sig is invalid, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/sigsetops.3 b/man3/sigsetops.3 index 6f3389029..4c0af1e2a 100644 --- a/man3/sigsetops.3 +++ b/man3/sigsetops.3 @@ -121,7 +121,7 @@ is not a member, and \-1 on error. .PP On error, these functions set .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/strdup.3 b/man3/strdup.3 index 8900a26d7..65ee22df9 100644 --- a/man3/strdup.3 +++ b/man3/strdup.3 @@ -109,7 +109,7 @@ function returns a pointer to the duplicated string. It returns NULL if insufficient memory was available, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B ENOMEM diff --git a/man3/sysconf.3 b/man3/sysconf.3 index 8c256421d..05eda466c 100644 --- a/man3/sysconf.3 +++ b/man3/sysconf.3 @@ -330,7 +330,7 @@ is one of the following: .IP * 3 On error, \-1 is returned and .I errno -is set to indicate the cause of the error +is set to indicate the error (for example, .BR EINVAL , indicating that diff --git a/man3/tempnam.3 b/man3/tempnam.3 index cb66c953a..1c450f375 100644 --- a/man3/tempnam.3 +++ b/man3/tempnam.3 @@ -102,7 +102,7 @@ On success, the function returns a pointer to a unique temporary filename. It returns NULL if a unique name cannot be generated, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B ENOMEM diff --git a/man3/timegm.3 b/man3/timegm.3 index de0fdc634..7779e85cc 100644 --- a/man3/timegm.3 +++ b/man3/timegm.3 @@ -71,7 +71,7 @@ On error, they return the value .I (time_t)\ \-1 and set .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B EOVERFLOW diff --git a/man3/uselocale.3 b/man3/uselocale.3 index 2018646ef..a3007313b 100644 --- a/man3/uselocale.3 +++ b/man3/uselocale.3 @@ -81,7 +81,7 @@ On error, it returns .IR "(locale_t)\ 0" , and sets .I errno -to indicate the cause of the error. +to indicate the error. .SH ERRORS .TP .B EINVAL diff --git a/man3/usleep.3 b/man3/usleep.3 index 7eaeb820a..519c5f0f2 100644 --- a/man3/usleep.3 +++ b/man3/usleep.3 @@ -69,7 +69,7 @@ The function returns 0 on success. On error, \-1 is returned, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B EINTR diff --git a/man3/wcsdup.3 b/man3/wcsdup.3 index 823cc18ba..a6e7a8328 100644 --- a/man3/wcsdup.3 +++ b/man3/wcsdup.3 @@ -56,7 +56,7 @@ On success, returns a pointer to the new wide-character string. On error, it returns NULL, with .I errno -set to indicate the cause of the error. +set to indicate the error. .SH ERRORS .TP .B ENOMEM