'\"macro stdmacro
.\"
.\" Copyright (c) 2022 Red Hat.  All Rights Reserved.
.\" Copyright (c) 2017 Ken McDonell.  All Rights Reserved.
.\"
.\" This program is free software; you can redistribute it and/or modify it
.\" under the terms of the GNU General Public License as published by the
.\" Free Software Foundation; either version 2 of the License, or (at your
.\" option) any later version.
.\"
.\" This program is distributed in the hope that it will be useful, but
.\" WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY
.\" or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License
.\" for more details.
.\"
.\"
.TH PMTIMESPECNOW 3 "PCP" "Performance Co-Pilot"
.SH NAME
\f3pmtimespecNow\f1,
\f3pmtimespecInc\f1,
\f3pmtimespecDec\f1,
\f3pmtimespecAdd\f1,
\f3pmtimespecSub\f1,
\f3pmtimespecToReal\f1,
\f3pmtimespecFromReal\f1,
\f3pmtimespecTotimeval\f1,
\f3pmtimespecPrint\f1,
\f3pmtimespecPrintInterval\f1 \- helper routines for time stored as a struct timespec
.SH "C SYNOPSIS"
.ft 3
.ad l
.hy 0
#include <pcp/pmapi.h>
.sp
void pmtimespecNow(struct timespec *\fItp\fP);
.br
void pmtimespecInc(struct timespec *\fIap\fP, const struct timespec *\fIbp\fP);
.br
void pmtimespecDec(struct timespec *\fIap\fP, const struct timespec *\fIbp\fP);
.br
double pmtimespecAdd(const struct timespec *\fIap\fP,
'in +\w'double pmtimespecAdd('u
const\ struct\ timespec\ *\fIbp\fP);
.in
.br
double pmtimespecSub(const struct timespec *\fIap\fP,
'in +\w'double pmtimespecSub('u
const\ struct\ timespec\ *\fIbp\fP);
.in
.br
double pmtimespecToReal(const struct timespec *\fItp\fP);
.br
void pmtimespecFromReal(double \fIsecs\fP, struct timespec *\fItp\fP);
.br
void pmtimespecTotimeval(struct timespec *\fItsp, \fPstruct timeval *\fItvp\fP);
.br
void pmtimespecPrint(FILE *\fIf\fP, const struct timespec *\fItp\fP);
.br
void pmtimespecPrintInterval(FILE *\fIf\fP, const struct timespec *\fItp\fP);
.sp
cc ... \-lpcp
.hy
.ad
.ft 1
.SH DESCRIPTION
.B pmtimespecNow
is a platform-independent method that returns the current system time
since the Epoch in
.IR tp .
.PP
.B pmtimespecInc
adds the time in
.I ap
to the time in
.I bp
and stores the result in
.IR ap .
Similarly
.B pmtimespecDec
subtracts the time in
.I bp
from the time in
.I ap
and stores the result in
.IR ap .
.PP
.B pmtimespecAdd
(and
.BR pmtimespecSub )
add (and subtract) times and return the result as a double value.
The time in the
.I ap
argument is not changed.
.PP
.B pmtimespecToReal
converts the time in
.I tp
to an equivalent double value.
.B pmtimespecFromReal
provides the reverse conversion, taking the time in
.I secs
and returning the equivalent time in
.IR tp .
.PP
.B pmtimespecTotimeval
converts the struct timespec
.I tsp
into an equivalent struct timeval
.I tvp
(modulo nanosecond to microsecond truncation).
.PP
For
.BR pmtimespecAdd ,
.BR pmtimespecSub ,
.BR pmtimespecToReal
and
.B pmtimespecFromReal
there is an issue of numerical precision.
If the
.B double
result or operand has more than 6 decimal digits of precision in the seconds
part of the value, then the fractional value is converted to microseconds
before arithmetic computations, so the nanoseconds field is only
accurate to 6 decimal digits in this case.
.PP
.B pmtimespecPrint
prints the timestamp from
.I tp
on the stream
.I f
in the local time (as returned by
.BR pmLocaltime (3))
in the format HH:MM:SS.XXXXXXXXX.
.PP
.B pmtimespecPrintInterval
prints the interval from
.I tp
on the stream
.I f
in a minimalist format [[HH\fBh\fP]MM\fBm\fP]SS[.XXXXXXXXX]\fBs\fP where
the hours, minutes and nanoseconds are only reported if they are non-zero,
and any trailing zeroes in the nanoseconds are omitted.
For example
if tp->tv_sec was 75 and tp->tv_nsec was 51000000 then the output would be
.BR 1h15.51s .
.SH NOTES
For variants of these interfaces using microsecond precision
and the timeval structure, refer to
.BR pmtimevalNow (3).
.SH COMPATIBILITY
Prior to PCP 7.0 the routine
.B pmtimespecPrint
was called
.BR pmPrintHighResStamp .
To support PMAPI transition, the old routine can still be used
if applications are recompiled with
.BR \-DPMAPI_VERSION=2 .
.PP
.B pmPrintHighResStamp
is now deprecated and compile-time support for
this routine name will be removed in a future release.
.SH SEE ALSO
.BR PMAPI (3),
.BR pmLocaltime (3)
and
.BR pmtimevalNow (3).

.\" control lines for scripts/man-spell
.\" +ok+ XXXXXXXXX HH SS {all from HH:MM:SS.XXXXXXXXX}