Sorry for the delay. On Thu, Nov 10, 2022 at 08:19:51PM +0100, Ingo Schwarze wrote: > Hi Scott, > > thanks for repeatedly working on time-related library documentation. :-) > > Unless noted otherwise, i agree with Todd's comments. > > Todd C. Miller wrote on Wed, Nov 09, 2022 at 10:31:15AM -0700: > > On Wed, 09 Nov 2022 16:47:22 +0000, Scott Cheloha wrote: > > >> RETURN VALUES > >> > >> - Pull ERRORS into this section. No need to put the one error in a > >> .Bl/.El, we can just mention it inline. > > > OK > > I somewhat strongly object to this change. > > If there is content for a standard section, that section ought to > be present, even if it is very short. The point is that a manual > page should not only contain the expected information, but all that > information should also be in the expected places, such that by merely > looking at the section headers, you can already tell whether a given > standard section has content, without reading any of the text. > > For example, the RETURN VALUES section ought to be absent if and only > if all functions documented in the page are void. > > For example, the ERRORS section ought to be absent if and only if > none of the functions ever touch the errno. Admittedly, our pages > may not be perfect in that respect, some libc pages may be missing > an ERRORS section even though the functions in questions sometimes > set errno, but that's a (mild) defect. We certainly should not > delete an existing ERRORS section for a function that definitely does > set the errno.
Alright, I see your point. > Also, in sections with a strongly conventional syntax (like ERRORS), > it is preferable to use the standard syntax even in corner cases. > In this case, yes, i do recommend a list with a single element. > Similarly, a utility program that can take exactly one option still > gets the standard DESCRIPTION sentence "The options are as follows:" > and then a one-element list. The advantage for readers is having the > familiar layout, and for developers the update becomes easier when > the second option is added; not that anything will ever be added to > pause(3), but consistency in style is still a good thing. Similarly, > in code, using getopt(3) is recommended even in a program that only > takes a single option. 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". Check if my tweak in the attached patch feels right. > >> SEE ALSO > >> > >> - Nix select(2) and setitimer(2), they aren't directly relevant. > > > OK. The reason select(2) is there is probably because you can > > emulate pause() using select(). > > I don't feel strongly about this. > > Removing select(2) is probably OK because the reason explained > by Todd is mostly historical. In Perl, you still use select() > to sleep for less than one second, but that's irrelevant to C > programming. > > I'm less convinced about removing setitimer(2). To me, setitimer(2) > feels just as relevant as kill(2). Both cause signals to be delivered > (asap or later), which is quite relevant because that causes pause(3) > to return. That makes sense to me. We'll keep setitimer(2). > >> HISTORY > >> > >> - We still have sigpause(3) and sigblock(3) in userspace. Should > >> we .Xr them? They aren't systems calls anymore, but they were > >> at that time. Unsure what to do here. > > Polishing the HISTORY section should in no case hold up your other > work. > > > I think it is better to use .Fn for sigpause(3) and sigblock(3) > > rather than .Xr here. > > In this very special case, where sigpause(3) and sigblock(3) are > strongly deprecated, i agree. Pointing out their continued existence - > even below HISTORY - risks accidentally encouraging their use. > > > Note that in 4.3-Reno pause(3) was still implemented in terms of > > sigpause(3) and sigblock(3), it is just that those functions were > > themselves wrappers instead of system calls. Personally, I would > > drop the bit about 4.3-Reno since it is not really correct in my > > opinion. > > It could be argued either way: IMHO, a wrapper around a wrapper around > foo is still a wrapper around foo, so at least my version that's > currently in the tree can be argued to be correct. Admittedly, Scott's > version less so; pause(3) certainly wasn't reimplemented for Reno. > Then again, replacing the last phase (starting at "and around") > with the following would avoid the semantic disagreement: > > It has been using sigsuspend(2) and sigprocmask(2) since 4.3-BSD Reno. I am just going to leave the History section alone. -- How are we looking? 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
