Re: Minor improvement to socket(2) man page
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
Re: Minor improvement to socket(2) man page
Philip Guenther wrote: > On Wed, Sep 21, 2016 at 6:23 PM, Michael McConville 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. > > 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.
Re: Minor improvement to socket(2) man page
On Wed, Sep 21, 2016 at 6:23 PM, Michael McConville 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. Some consistency that doesn't sacrifice clarity would be nice...
Minor improvement to socket(2) man page
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 - 1.41 +++ lib/libc/sys/socket.2 22 Sep 2016 01:20:30 - @@ -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
