[2/2] clock_nanosleep.2, nanosleep.2: Use 'duration' rather than 'request'

  It seems much more clear.

Suggested-by: Elliott Hughes <enh@google.com>
Cc: Stefan Puiu <stefan.puiu@gmail.com>
Cc: Bruno Haible <bruno@clisp.org>
Signed-off-by: Alejandro Colomar <alx@kernel.org>
---
 man2/clock_nanosleep.2 | 20 ++++++++++----------
 man2/nanosleep.2       | 12 ++++++------
 2 files changed, 16 insertions(+), 16 deletions(-)
  

Alejandro Colomar wrote:
>  man2/clock_nanosleep.2 | 20 ++++++++++----------
>  man2/nanosleep.2       | 12 ++++++------

The change to nanosleep.2 seems mostly fine. Except that the
term "requested relative duration" (line 142) raises questions;
what about changing that to "requested duration"?

The change to clock_nanosleep.2 seems wrong. There are two cases
(quoting the old text):

       If flags is 0, then the value specified in request is interpreted
       as an interval relative to the  current  value  of  the  clock
       specified by clockid.

       If  flags  is  TIMER_ABSTIME,  then request is interpreted as an
       absolute time as measured by the clock, clockid.  If request is
       less than or equal to the current value of the clock, then
       clock_nanosleep() returns immediately without suspending the  calling
       thread.

In the first case, the argument is a duration. In the second case, the
argument is an absolute time point; it would be wrong and very confusing
to denote it as "duration".

Bruno
  

Hi Bruno,

On Sun, Mar 03, 2024 at 01:45:37PM +0100, Bruno Haible wrote:
> Alejandro Colomar wrote:
> >  man2/clock_nanosleep.2 | 20 ++++++++++----------
> >  man2/nanosleep.2       | 12 ++++++------
> 
> The change to nanosleep.2 seems mostly fine. Except that the
> term "requested relative duration" (line 142) raises questions;
> what about changing that to "requested duration"?

Yeah, I had doubts about that one.  Probably I should drop 'relative'.

> 
> The change to clock_nanosleep.2 seems wrong. There are two cases
> (quoting the old text):
> 
>        If flags is 0, then the value specified in request is interpreted
>        as an interval relative to the  current  value  of  the  clock
>        specified by clockid.
> 
>        If  flags  is  TIMER_ABSTIME,  then request is interpreted as an
>        absolute time as measured by the clock, clockid.  If request is
>        less than or equal to the current value of the clock, then
>        clock_nanosleep() returns immediately without suspending the  calling
>        thread.
> 
> In the first case, the argument is a duration. In the second case, the
> argument is an absolute time point; it would be wrong and very confusing
> to denote it as "duration".

Hmm, thanks!  I guess we'll have to keep 'request' in clock_nanosleep(3)
unless someone comes up with a better name.  Elliott, you may want to
partially revert that change in bionic.

Have a lovely day!
Alex
  

On Sun, Mar 3, 2024 at 4:55 AM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Bruno,
>
> On Sun, Mar 03, 2024 at 01:45:37PM +0100, Bruno Haible wrote:
> > Alejandro Colomar wrote:
> > >  man2/clock_nanosleep.2 | 20 ++++++++++----------
> > >  man2/nanosleep.2       | 12 ++++++------
> >
> > The change to nanosleep.2 seems mostly fine. Except that the
> > term "requested relative duration" (line 142) raises questions;
> > what about changing that to "requested duration"?
>
> Yeah, I had doubts about that one.  Probably I should drop 'relative'.
>
> >
> > The change to clock_nanosleep.2 seems wrong. There are two cases
> > (quoting the old text):
> >
> >        If flags is 0, then the value specified in request is interpreted
> >        as an interval relative to the  current  value  of  the  clock
> >        specified by clockid.
> >
> >        If  flags  is  TIMER_ABSTIME,  then request is interpreted as an
> >        absolute time as measured by the clock, clockid.  If request is
> >        less than or equal to the current value of the clock, then
> >        clock_nanosleep() returns immediately without suspending the  calling
> >        thread.
> >
> > In the first case, the argument is a duration. In the second case, the
> > argument is an absolute time point; it would be wrong and very confusing
> > to denote it as "duration".
>
> Hmm, thanks!  I guess we'll have to keep 'request' in clock_nanosleep(3)
> unless someone comes up with a better name.  Elliott, you may want to
> partially revert that change in bionic.

thanks! https://android-review.googlesource.com/c/platform/bionic/+/2987070
changes to

/**
 * [clock_nanosleep(2)](http://man7.org/linux/man-pages/man2/clock_nanosleep.2.html)
 * sleeps for the given time (or until the given time if the TIMER_ABSTIME flag
 * is used), as measured by the given clock.
 *
 * Returns 0 on success, and returns -1 and returns an error number on failure.
 * If the sleep was interrupted by a signal, the return value will be `EINTR`
 * and `remainder` will be the amount of time remaining.
 */
int clock_nanosleep(clockid_t __clock, int __flags, const struct
timespec* _Nonnull __time, struct timespec* _Nullable __remainder);


> Have a lovely day!
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.
  

Hi Elliott,

On Mon, Mar 04, 2024 at 04:18:28PM -0800, enh wrote:
> thanks! https://android-review.googlesource.com/c/platform/bionic/+/2987070
> changes to
> 
> /**
>  * [clock_nanosleep(2)](http://man7.org/linux/man-pages/man2/clock_nanosleep.2.html)
>  * sleeps for the given time (or until the given time if the TIMER_ABSTIME flag
>  * is used), as measured by the given clock.
>  *
>  * Returns 0 on success, and returns -1 and returns an error number on failure.
>  * If the sleep was interrupted by a signal, the return value will be `EINTR`
>  * and `remainder` will be the amount of time remaining.
>  */
> int clock_nanosleep(clockid_t __clock, int __flags, const struct
> timespec* _Nonnull __time, struct timespec* _Nullable __remainder);

Hmmmm, that's the best name, meaningfully, I think.  But I've been
trying to avoid it.  I don't like using names of standard functions in
identifiers; it might confuse.  As an alternative, I thought of 't'.
What do you think?

Have a lovely night!

Alex
  

On Mon, Mar 4, 2024 at 4:34 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> Hi Elliott,
>
> On Mon, Mar 04, 2024 at 04:18:28PM -0800, enh wrote:
> > thanks! https://android-review.googlesource.com/c/platform/bionic/+/2987070
> > changes to
> >
> > /**
> >  * [clock_nanosleep(2)](http://man7.org/linux/man-pages/man2/clock_nanosleep.2.html)
> >  * sleeps for the given time (or until the given time if the TIMER_ABSTIME flag
> >  * is used), as measured by the given clock.
> >  *
> >  * Returns 0 on success, and returns -1 and returns an error number on failure.
> >  * If the sleep was interrupted by a signal, the return value will be `EINTR`
> >  * and `remainder` will be the amount of time remaining.
> >  */
> > int clock_nanosleep(clockid_t __clock, int __flags, const struct
> > timespec* _Nonnull __time, struct timespec* _Nullable __remainder);
>
> Hmmmm, that's the best name, meaningfully, I think.  But I've been
> trying to avoid it.  I don't like using names of standard functions in
> identifiers; it might confuse.  As an alternative, I thought of 't'.
> What do you think?

as you can see, i've taken the "the leading `__` means we get to
trample whatever we like" approach :-)

(we build bionic with hidden visibility and an explicit list of
symbols for the linker to export, so we'd have to be trying quite hard
to trip over ourselves.)

> Have a lovely night!
>
> Alex
>
> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.
  

On Mon, Mar 04, 2024 at 04:56:13PM -0800, enh wrote:
> > > int clock_nanosleep(clockid_t __clock, int __flags, const struct
> > > timespec* _Nonnull __time, struct timespec* _Nullable __remainder);
> >
> > Hmmmm, that's the best name, meaningfully, I think.  But I've been
> > trying to avoid it.  I don't like using names of standard functions in
> > identifiers; it might confuse.  As an alternative, I thought of 't'.
> > What do you think?
> 
> as you can see, i've taken the "the leading `__` means we get to
> trample whatever we like" approach :-)
> 
> (we build bionic with hidden visibility and an explicit list of
> symbols for the linker to export, so we'd have to be trying quite hard
> to trip over ourselves.)

Yeah, I was worried about the manual page  :)
  

On Mon, Mar 4, 2024 at 5:11 PM Alejandro Colomar <alx@kernel.org> wrote:
>
> On Mon, Mar 04, 2024 at 04:56:13PM -0800, enh wrote:
> > > > int clock_nanosleep(clockid_t __clock, int __flags, const struct
> > > > timespec* _Nonnull __time, struct timespec* _Nullable __remainder);
> > >
> > > Hmmmm, that's the best name, meaningfully, I think.  But I've been
> > > trying to avoid it.  I don't like using names of standard functions in
> > > identifiers; it might confuse.  As an alternative, I thought of 't'.
> > > What do you think?
> >
> > as you can see, i've taken the "the leading `__` means we get to
> > trample whatever we like" approach :-)
> >
> > (we build bionic with hidden visibility and an explicit list of
> > symbols for the linker to export, so we'd have to be trying quite hard
> > to trip over ourselves.)
>
> Yeah, I was worried about the manual page  :)

yeah, i think "t + extra text" makes sense there. i just try to be as
brief as possible in the doc comments on the assumption that most
readers will be seeing them in IDE pop-ups, and anyone who wants lots
of text will click through to the man page anyway. and at that point
they're your problem :-)

> --
> <https://www.alejandro-colomar.es/>
> Looking for a remote C programming job at the moment.