Re: [PATCH 1/4] clock_getres.2, clock_nanosleep.2, io_getevents.2, nanosleep.2, poll.2, sched_rr_get_interval.2, select.2, sigwaitinfo.2, timer_settime.2, timerfd_create.2, utimensat.2, mq_receive.3, mq_send.3, pthread_tryjoin_np.3, sem_wait.3, system_data_types.7: standardise on struct timespec fields comments to ucase w/tv_nsec range

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi наб,

On 11/28/21 19:17, наб wrote:
> Signed-off-by: Ahelenia Ziemiańska <nabijaczleweli@nabijaczleweli.xyz>

Regarding the addition of the range in the comments, I like it.

However, instead of repeating the information in all pages that repeat 
the definition of 'struct timespec', I'd go one step further: remove all 
of those redefinitions, and instead add a reference to timespec(3).  If 
any of those redefinitions contains any information that is not in 
timespec(3) (a.k.a. system_data_types(7)), then add it to timespec(3).

That way we can control the accurateness of that info by having it 
centralized, and save electronic ink :)


Cheers,

Alex

> ---
>   man2/clock_getres.2          | 4 ++--
>   man2/clock_nanosleep.2       | 4 ++--
>   man2/io_getevents.2          | 4 ++--
>   man2/nanosleep.2             | 4 ++--
>   man2/poll.2                  | 4 ++--
>   man2/sched_rr_get_interval.2 | 4 ++--
>   man2/select.2                | 6 +++---
>   man2/sigwaitinfo.2           | 4 ++--
>   man2/timer_settime.2         | 2 +-
>   man2/timerfd_create.2        | 2 +-
>   man2/utimensat.2             | 4 ++--
>   man3/mq_receive.3            | 4 ++--
>   man3/mq_send.3               | 4 ++--
>   man3/pthread_tryjoin_np.3    | 4 ++--
>   man7/system_data_types.7     | 2 +-
>   15 files changed, 28 insertions(+), 28 deletions(-)
> 
> diff --git a/man2/clock_getres.2 b/man2/clock_getres.2
> index c2bb492b9..f94b69d3c 100644
> --- a/man2/clock_getres.2
> +++ b/man2/clock_getres.2
> @@ -93,8 +93,8 @@ structures, as specified in
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t   tv_sec;        /* seconds */
> -    long     tv_nsec;       /* nanoseconds */
> +    time_t   tv_sec;        /* Seconds */
> +    long     tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/clock_nanosleep.2 b/man2/clock_nanosleep.2
> index b8c4afc2c..e6386e6a5 100644
> --- a/man2/clock_nanosleep.2
> +++ b/man2/clock_nanosleep.2
> @@ -64,8 +64,8 @@ structures, defined as follows:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;        /* seconds */
> -    long   tv_nsec;       /* nanoseconds [0 .. 999999999] */
> +    time_t tv_sec;        /* Seconds */
> +    long   tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/io_getevents.2 b/man2/io_getevents.2
> index 7c7e625bf..08738e413 100644
> --- a/man2/io_getevents.2
> +++ b/man2/io_getevents.2
> @@ -46,8 +46,8 @@ and is specified as a relative timeout in a structure of the following form:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;      /* seconds */
> -    long   tv_nsec;     /* nanoseconds [0 .. 999999999] */
> +    time_t tv_sec;      /* Seconds */
> +    long   tv_nsec;     /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/nanosleep.2 b/man2/nanosleep.2
> index 89d8577db..993007e92 100644
> --- a/man2/nanosleep.2
> +++ b/man2/nanosleep.2
> @@ -84,8 +84,8 @@ It is defined as follows:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;        /* seconds */
> -    long   tv_nsec;       /* nanoseconds */
> +    time_t tv_sec;        /* Seconds */
> +    long   tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/poll.2 b/man2/poll.2
> index 205468f3e..620528ec7 100644
> --- a/man2/poll.2
> +++ b/man2/poll.2
> @@ -329,8 +329,8 @@ This argument is a pointer to a structure of the following form:
>   .in +4n
>   .EX
>   struct timespec {
> -    long    tv_sec;         /* seconds */
> -    long    tv_nsec;        /* nanoseconds */
> +    long    tv_sec;         /* Seconds */
> +    long    tv_nsec;        /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/sched_rr_get_interval.2 b/man2/sched_rr_get_interval.2
> index 93db938df..1f249572b 100644
> --- a/man2/sched_rr_get_interval.2
> +++ b/man2/sched_rr_get_interval.2
> @@ -54,8 +54,8 @@ structure has the following form:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;    /* seconds */
> -    long   tv_nsec;   /* nanoseconds */
> +    time_t tv_sec;    /* Seconds */
> +    long   tv_nsec;   /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/select.2 b/man2/select.2
> index aee25c52c..fd9a994eb 100644
> --- a/man2/select.2
> +++ b/man2/select.2
> @@ -345,7 +345,7 @@ is a structure of the following type:
>   .in +4n
>   .EX
>   struct timeval {
> -    time_t      tv_sec;         /* seconds */
> +    time_t      tv_sec;         /* Seconds */
>       suseconds_t tv_usec;        /* microseconds */
>   };
>   .EE
> @@ -358,8 +358,8 @@ has the following type:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t      tv_sec;         /* seconds */
> -    long        tv_nsec;        /* nanoseconds */
> +    time_t      tv_sec;         /* Seconds */
> +    long        tv_nsec;        /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man2/sigwaitinfo.2 b/man2/sigwaitinfo.2
> index 00bc50485..716661479 100644
> --- a/man2/sigwaitinfo.2
> +++ b/man2/sigwaitinfo.2
> @@ -93,8 +93,8 @@ This argument is of the following type:
>   .in +4n
>   .EX
>   struct timespec {
> -    long    tv_sec;         /* seconds */
> -    long    tv_nsec;        /* nanoseconds */
> +    long    tv_sec;         /* Seconds */
> +    long    tv_nsec;        /* Nanoseconds [0 .. 999999999] */
>   }
>   .EE
>   .in
> diff --git a/man2/timer_settime.2 b/man2/timer_settime.2
> index 10687b211..1c8d7fa17 100644
> --- a/man2/timer_settime.2
> +++ b/man2/timer_settime.2
> @@ -67,7 +67,7 @@ structure is defined as follows:
>   .EX
>   struct timespec {
>       time_t tv_sec;                /* Seconds */
> -    long   tv_nsec;               /* Nanoseconds */
> +    long   tv_nsec;               /* Nanoseconds [0 .. 999999999] */
>   };
>   
>   struct itimerspec {
> diff --git a/man2/timerfd_create.2 b/man2/timerfd_create.2
> index 65fdfcc45..832ec4b68 100644
> --- a/man2/timerfd_create.2
> +++ b/man2/timerfd_create.2
> @@ -159,7 +159,7 @@ each of which is in turn a structure of type
>   .EX
>   struct timespec {
>       time_t tv_sec;                /* Seconds */
> -    long   tv_nsec;               /* Nanoseconds */
> +    long   tv_nsec;               /* Nanoseconds [0 .. 999999999] */
>   };
>   
>   struct itimerspec {
> diff --git a/man2/utimensat.2 b/man2/utimensat.2
> index cb5f6b693..19fa8c677 100644
> --- a/man2/utimensat.2
> +++ b/man2/utimensat.2
> @@ -93,8 +93,8 @@ This information is conveyed in a structure of the following form:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;        /* seconds */
> -    long   tv_nsec;       /* nanoseconds */
> +    time_t tv_sec;        /* Seconds */
> +    long   tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man3/mq_receive.3 b/man3/mq_receive.3
> index df463297d..4dac43643 100644
> --- a/man3/mq_receive.3
> +++ b/man3/mq_receive.3
> @@ -97,8 +97,8 @@ specified in the following structure:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;        /* seconds */
> -    long   tv_nsec;       /* nanoseconds */
> +    time_t tv_sec;        /* Seconds */
> +    long   tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man3/mq_send.3 b/man3/mq_send.3
> index 54999f440..6b3fbe98a 100644
> --- a/man3/mq_send.3
> +++ b/man3/mq_send.3
> @@ -106,8 +106,8 @@ specified in the following structure:
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;        /* seconds */
> -    long   tv_nsec;       /* nanoseconds */
> +    time_t tv_sec;        /* Seconds */
> +    long   tv_nsec;       /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man3/pthread_tryjoin_np.3 b/man3/pthread_tryjoin_np.3
> index e912f8e3b..10b498c80 100644
> --- a/man3/pthread_tryjoin_np.3
> +++ b/man3/pthread_tryjoin_np.3
> @@ -79,8 +79,8 @@ specifying an absolute time measured since the Epoch (see
>   .in +4n
>   .EX
>   struct timespec {
> -    time_t tv_sec;     /* seconds */
> -    long   tv_nsec;    /* nanoseconds */
> +    time_t tv_sec;     /* Seconds */
> +    long   tv_nsec;    /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .in
> diff --git a/man7/system_data_types.7 b/man7/system_data_types.7
> index d117b1d2b..1e6a3f74c 100644
> --- a/man7/system_data_types.7
> +++ b/man7/system_data_types.7
> @@ -1544,7 +1544,7 @@ or
>   .EX
>   struct timespec {
>       time_t  tv_sec;  /* Seconds */
> -    long    tv_nsec; /* Nanoseconds */
> +    long    tv_nsec; /* Nanoseconds [0 .. 999999999] */
>   };
>   .EE
>   .PP
> 

-- 
Alejandro Colomar
Linux man-pages comaintainer; http://www.kernel.org/doc/man-pages/