Minor improvement to socket(2) man page

classic Classic list List threaded Threaded
4 messages Options
Reply | Threaded
Open this post in threaded view
|

Minor improvement to socket(2) man page

Michael McConville-3
The current version is somewhat awkward and forgets to mention that
errno is set. I adapted the paragraph found in most other system call
man pages.

Thanks for your time,
Mike


Index: lib/libc/sys/socket.2
===================================================================
RCS file: /cvs/src/lib/libc/sys/socket.2,v
retrieving revision 1.41
diff -u -p -u -r1.41 socket.2
--- lib/libc/sys/socket.2 19 Mar 2016 22:10:49 -0000 1.41
+++ lib/libc/sys/socket.2 22 Sep 2016 01:20:30 -0000
@@ -219,8 +219,11 @@ and
 .Xr getsockopt 2
 are used to set and get options, respectively.
 .Sh RETURN VALUES
-A \-1 is returned if an error occurs, otherwise the return
-value is a descriptor referencing the socket.
+Upon successful completion, a descriptor referencing the socket is
+returned. Otherwise, the value \-1 is returned and the global
+variable
+.Va errno
+is set to indicate the error.
 .Sh ERRORS
 The
 .Fn socket

Reply | Threaded
Open this post in threaded view
|

Re: Minor improvement to socket(2) man page

Philip Guenther-2
On Wed, Sep 21, 2016 at 6:23 PM, Michael McConville <[hidden email]> wrote:
> The current version is somewhat awkward and forgets to mention that
> errno is set. I adapted the paragraph found in most other system call
> man pages.

There are six syscalls that return an fd on success...and their
manpages all have totally different wording for the return value.
Whee.

accept
     The call returns -1 on error.  If it succeeds, it returns a non-negative
     integer that is a descriptor for the accepted socket.

fhopen
     Upon successful completion, fhopen() returns the file descriptor for the
     opened file, while fhstat() and fhstatfs() return 0.  Otherwise, -1 is
     returned and errno is set to indicate the error.

kqueue
     kqueue() creates a new kernel event queue and returns a file descriptor.
     If there was an error creating the kernel event queue, a value of -1 is
     returned and errno set.

open
     If successful, open() returns a non-negative integer, termed a file
     descriptor.  Otherwise, a value of -1 is returned and errno is set to
     indicate the error.

openat: same manpage as open but totally unmentioned in the RETURN
VALUES section

socket
     A -1 is returned if an error occurs, otherwise the return value is a
     descriptor referencing the socket.

<sigh>  Some consistency that doesn't sacrifice clarity would be nice...

Reply | Threaded
Open this post in threaded view
|

Re: Minor improvement to socket(2) man page

Michael McConville-3
Philip Guenther wrote:

> On Wed, Sep 21, 2016 at 6:23 PM, Michael McConville <[hidden email]> wrote:
> > The current version is somewhat awkward and forgets to mention that
> > errno is set. I adapted the paragraph found in most other system call
> > man pages.
>
> There are six syscalls that return an fd on success...and their
> manpages all have totally different wording for the return value.
> Whee.
>
> accept
>      The call returns -1 on error.  If it succeeds, it returns a non-negative
>      integer that is a descriptor for the accepted socket.
>
> fhopen
>      Upon successful completion, fhopen() returns the file descriptor for the
>      opened file, while fhstat() and fhstatfs() return 0.  Otherwise, -1 is
>      returned and errno is set to indicate the error.
>
> kqueue
>      kqueue() creates a new kernel event queue and returns a file descriptor.
>      If there was an error creating the kernel event queue, a value of -1 is
>      returned and errno set.
>
> open
>      If successful, open() returns a non-negative integer, termed a file
>      descriptor.  Otherwise, a value of -1 is returned and errno is set to
>      indicate the error.
>
> openat: same manpage as open but totally unmentioned in the RETURN
> VALUES section
>
> socket
>      A -1 is returned if an error occurs, otherwise the return value is a
>      descriptor referencing the socket.
>
> <sigh>  Some consistency that doesn't sacrifice clarity would be nice...

Before I do the busy-work: do the man page gurus have a preferred
phrasing? I prefer fhopen(2)'s (listed above), which seems to be the
most common.

Reply | Threaded
Open this post in threaded view
|

Re: Minor improvement to socket(2) man page

Ingo Schwarze
Hi,

Michael McConville wrote on Wed, Dec 21, 2016 at 08:17:20PM -0500:

> Before I do the busy-work: do the man page gurus have a preferred
> phrasing? I prefer fhopen(2)'s (listed above), which seems to be the
> most common.

The preferred version is something close to what .Rv produces:

  schwarze@isnote $ echo ".Rv\n.Pp\n.Rv foo" | mandoc -mdoc

  Upon successful completion, the value 0 is returned; otherwise the
  value -1 is returned and the global variable errno is set to indicate
  the error.

  The foo() function returns the value 0 if successful; otherwise the
  value -1 is returned and the global variable errno is set to indicate
  the error.

That gives, for a page with one function, or if all functions have
the same return values, taking accept(2) as an example:

  Upon successful completion, a non-negative integer representing
  the file descriptor for the accepted socket is returned;
  otherwise the value -1 is returned and the global variable
  .Va errno
  is set to indicate the error.

I think fhopen(3) can remain as it is, even though it differs in a
few very small details.

Yours,
  Ingo