V2: timespec_get (3)

V2: timespec_get (3)

[Walter Harms]

.\" Process this file with
.\" groff -man -Tascii foo.1
.\"
.ds N1 The example is simplified code and not production ready.

.TH TIMESPEC_GET  1 "2021-04-20" Linux "Linux Programmer's Manual"
.SH NAME
timespec_get \- get current time as struct timespec
.SH SYNOPSIS
.B #include <time.h>
.PP
.BI "int timespec_get( struct timespec *" ts ", int " base ");"
.SH DESCRIPTION
The function 
.B timespec_get()
fills the argument
.I ts
with the current time. The type   
.I struct timespec
is specified as:
.PP
.in +4n
.EX
struct timespec
{
   time_t tv_sec;  /* Seconds.  */
   long tv_nsec;   /* Nanoseconds.  */
};
.EE
.in
.PP
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. Anything else is 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 .
.PP
.in +4n
.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
.in
.PP
The example is simplified code and not production ready.
.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)