pmtimespec(3) — Linux manual page

NAME | C SYNOPSIS | DESCRIPTION | NOTES | COMPATIBILITY | SEE ALSO | COLOPHON

PMTIMESPECNOW(3)         Library Functions Manual        PMTIMESPECNOW(3)

NAME         top

       pmtimespecNow, pmtimespecInc, pmtimespecDec, pmtimespecAdd,
       pmtimespecSub, pmtimespecToReal, pmtimespecFromReal,
       pmtimespecTotimeval, pmtimespecPrint, pmtimespecPrintInterval -
       helper routines for time stored as a struct timespec

C SYNOPSIS         top

       #include <pcp/pmapi.h>

       void pmtimespecNow(struct timespec *tp);
       void pmtimespecInc(struct timespec *ap, const struct timespec
       *bp);
       void pmtimespecDec(struct timespec *ap, const struct timespec
       *bp);
       double pmtimespecAdd(const struct timespec *ap,
                            const struct timespec *bp);
       double pmtimespecSub(const struct timespec *ap,
                            const struct timespec *bp);
       double pmtimespecToReal(const struct timespec *tp);
       void pmtimespecFromReal(double secs, struct timespec *tp);
       void pmtimespecTotimeval(struct timespec *tsp, struct timeval
       *tvp);
       void pmtimespecPrint(FILE *f, const struct timespec *tp);
       void pmtimespecPrintInterval(FILE *f, const struct timespec *tp);

       cc ... -lpcp

DESCRIPTION         top

       pmtimespecNow  is  a  platform-independent method that returns the
       current system time since the Epoch in tp.

       pmtimespecInc adds the time in ap to the time in bp and stores the
       result in ap.  Similarly pmtimespecDec subtracts the  time  in  bp
       from the time in ap and stores the result in ap.

       pmtimespecAdd (and pmtimespecSub) add (and subtract) times and re‐
       turn the result as a double value.  The time in the ap argument is
       not changed.

       pmtimespecToReal  converts  the time in tp to an equivalent double
       value.  pmtimespecFromReal provides the reverse conversion, taking
       the time in secs and returning the equivalent time in tp.

       pmtimespecTotimeval converts  the  struct  timespec  tsp  into  an
       equivalent  struct  timeval  tvp (modulo nanosecond to microsecond
       truncation).

       For pmtimespecAdd,  pmtimespecSub,  pmtimespecToReal  and  pmtime‐
       specFromReal  there  is  an  issue of numerical precision.  If the
       double result or operand has more than 6 decimal digits of  preci‐
       sion  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.

       pmtimespecPrint  prints  the  timestamp from tp on the stream f in
       the local time (as  returned  by  pmLocaltime(3))  in  the  format
       HH:MM:SS.XXXXXXXXX.

       pmtimespecPrintInterval  prints the interval from tp on the stream
       f in  a  minimalist  format  [[HHh]MMm]SS[.XXXXXXXXX]s  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 1h15.51s.

NOTES         top

       For variants of these interfaces using microsecond  precision  and
       the timeval structure, refer to pmtimevalNow(3).

COMPATIBILITY         top

       Prior  to  PCP 7.0 the routine pmtimespecPrint was called pmPrint‐
       HighResStamp.  To support PMAPI transition, the  old  routine  can
       still  be  used  if  applications are recompiled with -DPMAPI_VER‐
       SION=2.

       pmPrintHighResStamp is now deprecated and compile-time support for
       this routine name will be removed in a future release.

SEE ALSO         top

       PMAPI(3), pmLocaltime(3) and pmtimevalNow(3).

COLOPHON         top

       This page is part of the PCP (Performance Co-Pilot) project.   In‐
       formation  about the project can be found at ⟨http://www.pcp.io/⟩.
       If you have a  bug  report  for  this  manual  page,  send  it  to
       [email protected].  This page was obtained from the project's upstream
       Git  repository ⟨https://github.com/performancecopilot/pcp.git⟩ on
       2025-08-11.  (At that time, the date of  the  most  recent  commit
       that was found in the repository was 2025-08-11.)  If you discover
       any  rendering  problems  in this HTML version of the page, or you
       believe there is a better or more up-to-date source for the  page,
       or you have corrections or improvements to the information in this
       COLOPHON  (which  is not part of the original manual page), send a
       mail to [email protected]

Performance Co-Pilot               PCP                   PMTIMESPECNOW(3)

Pages that refer to this page: pmtimeval(3)