* Re: timespec_get() part of C11
2021-04-24 17:41 timespec_get() part of C11 Walter Harms
@ 2021-04-28 20:20 ` Alejandro Colomar (man-pages)
0 siblings, 0 replies; 2+ messages in thread
From: Alejandro Colomar (man-pages) @ 2021-04-28 20:20 UTC (permalink / raw)
To: Walter Harms, linux-man@vger.kernel.org
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/
^ permalink raw reply [flat|nested] 2+ messages in thread