Re: timespec_get() part of C11

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

Hi Walter,

Thanks for the page!  Please see some comments below (I'll tell you more 
in the next iteration).

Cheers,

Alex

P.S.: How's it going with the other page you were working on? :)

On 4/24/21 7:41 PM, Walter Harms wrote:
> .\" Copyright (c) 2021 wharms
> .\" %%%LICENSE_START(VERBATIM)
> .\" Permission is granted to make and distribute verbatim copies of this
> .\" manual provided the copyright notice and this permission notice are
> .\" preserved on all copies.
> .\"
> .\" Permission is granted to copy and distribute modified versions of this
> .\" manual under the conditions for verbatim copying, provided that the
> .\" entire resulting derived work is distributed under the terms of a
> .\" permission notice identical to this one.
> .\"
> .\" Since the Linux kernel and libraries are constantly changing, this
> .\" manual page may be incorrect or out-of-date.  The author(s) assume no
> .\" responsibility for errors or omissions, or for damages resulting from
> .\" the use of the information contained herein.  The author(s) may not
> .\" have taken the same level of care in the production of this manual,
> .\" which is licensed free of charge, as they might when working
> .\" professionally.
> .\"
> .\" Formatted or processed versions of this manual, if unaccompanied by
> .\" the source, must acknowledge the copyright and authors of this work.
> .\" %%%LICENSE_END
> .\"
> .ds N1 The example is simplified code and not production ready.
> .de N2
> .SH COLOPHON
> This page is part of release 4.16 of the Linux

4.16? :)

> .I man-pages
> project.
> A description of the project,
> information about reporting bugs,
> and the latest version of this page,
> can be found at
> \%https://www.kernel.org/doc/man\-pages/.
> ..

You can remove the COLOPHON.   It is automatically created at release time.

> 
> .TH timespec_get  1 "2021-04-20" Linux "User Manuals"

Please, see `man 7 man-pages`, subsection 'Title line'.

> .SH NAME
> timespec_get  \- get time in high resolution

"high resolution" is relative.  It's like when you call Y is the "new 
X"... until it gets old.  I'd prefer expressing something like "get time 
in seconds and nanoseconds", don't you?

> .SH SYNOPSIS
> .B #include <time.h>
> .PP
> .BI "int timespec_get( struct timespec *"ts ", int " base  ");"

Don't add extra spaces inside the parentheses '( xxx', just like you'd 
do in normal english.
If there are no spaces, there's no need for using quotes: '");"' == ');'.
Also, use spaces to separate arguments to '.BI' always.

.BI "int timespec_get(struct timespec *" ts ", int " base );

> .SH DESCRIPTION
> The function
> .B timespec_get()
> will fill

No need to use future here.  'fills' is simpler.

> .I ts
> wth the current time. The argument is a

'The argument': I think I prefer to mention the argument name.

s/The argument /\n.I ts\n/?

> .I struct timespec
> what is specified like:
> .nf

Please, see `man 7 man-pages`, subsection 'Indentation of structure 
definitions, shell session logs, and so on'.

> struct timespec
> {
>     time_t tv_sec;     /* Seconds.  */
>     long tv_nsec;   /* Nanoseconds.  */

Please, align comments.

> };
> .fi
> The elements of the struct hold the seconds and nanoseconds since epoch.
> The system clock will round the nanosecond argument.
> .PP
> The second argument
> .B base
> indicate the time base.  POSIX requieres
> .I TIME_UTC
> only.  All  others are implementation defined.
> .SH RETURN VALUE
> The function will return
> .I base
> or 0 for failure.
> .SH EXAMPLE
> The example program will show the current time
> in YYYY-MM-DD hh:mm:ss and then the nanoseconds .
> .EX
> /* compile with:
>   *  gcc timespec.c -o timespec
>   */
> #include <stdio.h>
> #include <time.h>
>   
> int main(void)
> {
>      struct timespec ts;
>      char buf[30];
>      timespec_get(&ts, TIME_UTC);
>      strftime(buf, sizeof(buf), "%F %T", gmtime(&ts.tv_sec));
>      printf("Current time: %s ", buf);
>      printf("UTC and %ld nsec\\n", ts.tv_nsec);
>      return (0);
> }
> .EE
> \*(N1
> .SH NOTE
> This function is equal to the POSIX function
> .BR "clock_gettime(CLOCK_REALTIME, ts)" .
> .PP
> The ts.tv_sec is equal to the return value of
> .BR time(NULL) .
> .SH "CONFORMING TO"
> The function is a C11 requirement and appears first time in
> .BR "glibc 2.16 " .
> .SH "SEE ALSO"
> .BR clock_gettime(3) ,
> .BR time (2),
> .BR time (7)
> \*(N2
> 


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