Hi Scott, Scott Cheloha wrote on Sat, Dec 10, 2022 at 09:25:48AM -0600:
> Sure, I will keep the ERRORS section. > I think the current phrasing in ERRORS is odd, though. > "may set the global variable..." is what we normally say here, but it > isn't a "may" in this case, it's an "always". I wouldn't go as far as saying "'may set the global variable...' is what we normally say. It occurs in a very small number of section 3 manuals. It might occasionally make sense in section 3 because some library functions might fail both due to syscall failures and for other reasons not related to syscalls, in which case they may sometimes set errno and sometimes not - even though some library functions also set errno themselves, not relying on failing syscalls to do that. Even in section 3, i see less than ten instances: - __thrsleep(2) - clock_settime(2) - setlogin(2) - setrlimit(2) - read(2) - recv(2) - send(2) - truncate(2) - write(2) And all these only occur after the usual wording "will fail if". So it doesn't mean that any syscall can fail without setting errno; this wording merely indicates that for specific functions, additional errno values may occur instead of the ones listed right above. That said, if something is guaranteed to set errno, i clearly prefer saying so. Let's try to avoid needless ambiguity. > Check if my tweak in the attached patch feels right. I dislike the wording "return an error" for setting errno, even in the existing pages, in particular for a function that has an "int" return value. I see a slight risk of confusing people. Also, for this function, setting errno(2) does not really indicate any error, or does it? The function is a bit unusual in so far as it always returns the same value, never fails, always sets errno, and always to the same value, so the usual wordings don't fit too well. I would prefer something like this: .Fn pause blocks the calling thread until it receives an unmasked signal and then returns. .Sh RETURN VALUES .Fn pause always returns \-1. .Sh ERRORS .Fn pause always sets .Xr errno 2 to the following value: .Bl -tag -width Er .It Bq Er EINTR The call was interrupted by a signal. .El Feel free to use part or all of my ideas, or commit your patch commit as-is. OK schwarze@ either way. Yours, Ingo > Index: pause.3 > =================================================================== > RCS file: /cvs/src/lib/libc/gen/pause.3,v > retrieving revision 1.16 > diff -u -p -r1.16 pause.3 > --- pause.3 9 Nov 2022 06:48:29 -0000 1.16 > +++ pause.3 10 Dec 2022 15:23:47 -0000 > @@ -32,7 +32,7 @@ > .Os > .Sh NAME > .Nm pause > -.Nd stop until signal > +.Nd wait for a signal > .Sh SYNOPSIS > .In unistd.h > .Ft int > @@ -40,40 +40,31 @@ > .Sh DESCRIPTION > .Bf -symbolic > .Fn pause > -is made obsolete by > +is obsoleted by > .Xr sigsuspend 2 . > .Ef > .Pp > -The > .Fn pause > -function forces a process to pause until a signal is received from either the > -.Xr kill 2 > -function or an interval timer > -(see > -.Xr setitimer 2 ) . > -.Pp > -Upon termination of a signal handler started during a > -.Fn pause , > -the > -.Fn pause > -call will return. > +blocks the calling thread until it receives an unmasked signal. > .Sh RETURN VALUES > -Always returns \-1. > -.Sh ERRORS > -The > +On receipt of a signal, > .Fn pause > -function may set the global variable > +returns \-1 and the global variable > .Va errno > -to the following error: > +is set to indicate the error. > +.Sh ERRORS > +.Fn pause > +always returns the following error: > .Bl -tag -width Er > .It Bq Er EINTR > -The call was interrupted. > +The call was interrupted by a signal. > .El > .Sh SEE ALSO > .Xr kill 2 , > -.Xr select 2 , > .Xr setitimer 2 , > -.Xr sigsuspend 2 > +.Xr sigprocmask 2 , > +.Xr sigsuspend 2 , > +.Xr signal 3 > .Sh HISTORY > A > .Fn pause
