accept.2, epoll_create.2, inotify_add_watch.2, open.2, open_by_handle_at.2, pidfd_open.2, dirfd.3, posix_openpt.3, shm_open.3: Fix clumsy wording around "nonnegative file descriptors"

Reported-by: Christian Brauner <christian@brauner.io>
Signed-off-by: Michael Kerrisk <mtk.manpages@gmail.com>

man2/accept.2

@@ -169,8 +169,8 @@ flag in
 for reasons why this may be useful.
 .SH RETURN VALUE
 On success,
-these system calls return a nonnegative integer that is a file descriptor
-for the accepted socket.
+these system calls return a file descriptor
+for the accepted socket (a nonnegative integer).
 On error, \-1 is returned,
 .I errno
 is set appropriately, and

man2/epoll_create.2

@@ -78,7 +78,7 @@ for reasons why this may be useful.
 .SH RETURN VALUE
 On success,
 these system calls
-return a nonnegative file descriptor.
+return a file descriptor (a nonnegative integer).
 On error, \-1 is returned, and
 .I errno
 is set to indicate the error.

man2/inotify_add_watch.2

@@ -77,7 +77,7 @@ the object for which the event occurred.
 .SH RETURN VALUE
 On success,
 .BR inotify_add_watch ()
-returns a nonnegative watch descriptor.
+returns a watch descriptor (a nonnegative integer).
 On error, \-1 is returned and
 .I errno
 is set appropriately.

man2/open.2

@@ -962,7 +962,8 @@ It is separate documented, in
 .BR openat (),
 and
 .BR creat ()
-return the new file descriptor, or \-1 if an error occurred
+return the new file descriptor (a nonnegative integer),
+or \-1 if an error occurred
 (in which case,
 .I errno
 is set appropriately).

man2/open_by_handle_at.2

@@ -279,7 +279,7 @@ On success,
 returns 0,
 and
 .BR open_by_handle_at ()
-returns a nonnegative file descriptor.
+returns a file descriptor (a nonnegative integer).
 .PP
 In the event of an error, both system calls return \-1 and set
 .I errno

man2/pidfd_open.2

@@ -47,7 +47,7 @@ currently, this argument must be specified as 0.
 .SH RETURN VALUE
 On success,
 .BR pidfd_open ()
-returns a nonnegative file descriptor.
+returns a file descriptor (a nonnegative integer).
 On error, \-1 is returned and
 .I errno
 is set to indicate the cause of the error.

man3/dirfd.3

@@ -63,7 +63,9 @@ It will be automatically closed when
 .BR closedir (3)
 is called.
 .SH RETURN VALUE
-On success, a nonnegative file descriptor is returned.
+On success,
+.BR dirfd ()
+returns a file descriptor (a nonnegative integer).
 On error, \-1 is returned, and
 .I errno
 is set to indicate the cause of the error.

man3/posix_openpt.3

@@ -62,7 +62,7 @@ Do not make this device the controlling terminal for the process.
 .SH RETURN VALUE
 On success,
 .BR posix_openpt ()
-returns a nonnegative file descriptor which is the lowest
+returns a file descriptor (a nonnegative integer) which is the lowest
 numbered unused file descriptor.
 On failure, \-1 is returned, and
 .I errno

man3/shm_open.3

@@ -170,7 +170,7 @@ was specified, in which case a new, distinct object is created).
 .SH RETURN VALUE
 On success,
 .BR shm_open ()
-returns a nonnegative file descriptor.
+returns a file descriptor (a nonnegative integer).
 On failure,
 .BR shm_open ()
 returns \-1.