Hi Scott, Scott Cheloha wrote on Tue, Jul 27, 2021 at 05:15:09PM -0500: > On Mon, Jul 26, 2021 at 10:37:03AM -0600, Todd C. Miller wrote: >> On Mon, 26 Jul 2021 07:55:00 -0500, Scott Cheloha wrote:
>>> Still wondering whether we need an Errors section to mention that >>> sleep(3) can set errno. >> POSIX doesn't define any errors. Of the errors returned by nanosleep, >> only EINTR is really possible. I guess we could save & restore >> errno in sleep.c but I don't see any implementations that actually >> do that. I only checked illumos, glibc and musl though. > We definitely don't want to save/restore. > > I meant more like a simple acknowledgement for the programmer. > Knowing what can set errno is helpful. > > We do it for other library functions where some part of the > functionality is implemented with a system call. In other manpages we > say something like: > > The > .Fn foo > function may fail and set > .Va errno > for any of the errors specified for the > .Fn bar 2 > routine. > > See, e.g., `man 3 nice` or `man 3 fopen`. > > Then again, there's really only one error. That would sound like overkill to me, especially since millert@ pointed out that only EINTR is relevant. > Maybe we should just > duplicate the information in sleep.3. > > What about this? > > The > .Fn sleep > function sets > .Va errno > to > .Dv EINTR > if it is interrupted by the delivery of a signal. I like that: it seems correct, complete, and concise. OK schwarze@ for the patch as a whole. Feel free to use or discard the two suggestions provided in-line below as you see fit. Yours, Ingo > Index: sleep.3 > =================================================================== > RCS file: /cvs/src/lib/libc/gen/sleep.3,v > retrieving revision 1.16 > diff -u -p -r1.16 sleep.3 > --- sleep.3 8 Feb 2020 01:09:57 -0000 1.16 > +++ sleep.3 27 Jul 2021 22:13:22 -0000 > @@ -32,7 +32,7 @@ > .Os > .Sh NAME > .Nm sleep > -.Nd suspend process execution for interval measured in seconds > +.Nd suspend execution for an interval of seconds > .Sh SYNOPSIS > .In unistd.h > .Ft unsigned int > @@ -40,41 +40,46 @@ > .Sh DESCRIPTION > The > .Fn sleep > -function suspends execution of the calling process until either > +function suspends execution until at least the given number of In nanosleep(2), you say ... suspends execution of the calling thread ... Would that be useful here, too? > .Fa seconds > -seconds have elapsed or a signal is delivered to the process and its > -action is to invoke a signal-catching function or to terminate the > -process. > -The suspension time may be longer than requested due to the > -scheduling of other activity by the system. > +have elapsed or an unmasked signal is delivered to the calling thread. > .Pp > -This function is implemented using > -.Xr nanosleep 2 > -by pausing for > -.Fa seconds > -seconds or until a signal occurs. > -Consequently, in this implementation, > -sleeping has no effect on the state of process timers, > -and there is no special handling for > -.Dv SIGALRM . > +This version of > +.Fn sleep > +is implemented with > +.Xr nanosleep 2 , > +so delivery of any unmasked signal will terminate the sleep early, > +even if > +.Dv SA_RESTART > +is set with > +.Xr sigaction 2 > +for the interrupting signal. > .Sh RETURN VALUES > -If the > +If > +.Fn sleep > +sleeps for the full count of > +.Fa seconds > +it returns 0. > +Otherwise, > +.Fn sleep > +returns the number of seconds remaining from the original request. > +.Sh ERRORS > +The > .Fn sleep > -function returns because the requested time has elapsed, the value > -returned will be zero. > -If the > -.Fn sleep > -function returns due to the delivery of a signal, the value returned > -will be the unslept amount (the request time minus the time actually > -slept) in seconds. > +function sets > +.Va errno > +to > +.Dv EINTR > +if it is interrupted by the delivery of a signal. > .Sh SEE ALSO > .Xr sleep 1 , > -.Xr nanosleep 2 > +.Xr nanosleep 2 , > +.Xr sigaction 2 > .Sh STANDARDS > The > .Fn sleep > function conforms to > -.St -p1003.1-90 . > +.St -p1003.1-2008 . I would consider it useful to add this sentence here: Setting .Va errno is an extension to that specification.
