1 .\"
   2 .\" This file and its contents are supplied under the terms of the
   3 .\" Common Development and Distribution License ("CDDL"), version 1.0.
   4 .\" You may only use this file in accordance with the terms of version
   5 .\" 1.0 of the CDDL.
   6 .\"
   7 .\" A full copy of the text of the CDDL should have accompanied this
   8 .\" source.  A copy of the CDDL is also available via the Internet at
   9 .\" http://www.illumos.org/license/CDDL.
  10 .\"
  11 .\"
  12 .\" Copyright 2020 OmniOS Community Edition (OmniOSce) Association.
  13 .\"
  14 .Dd Sep 06, 2020
  15 .Dt timespec 3HEAD
  16 .Os
  17 .Sh NAME
  18 .Nm timespec ,
  19 .Nm timeval ,
  20 .Nm TIMESPEC_TO_TIMEVAL ,
  21 .Nm TIMEVAL_TO_TIMESPEC
  22 .Nd time structures and conversion
  23 .Sh SYNOPSIS
  24 .In sys/time.h
  25 .Ft void
  26 .Fo TIMESPEC_TO_TIMEVAL
  27 .Fa "struct timeval *tv"
  28 .Fa "const struct timespec *ts"
  29 .Fc
  30 .Ft void
  31 .Fo TIMEVAL_TO_TIMESPEC
  32 .Fa "const struct timeval *tv"
  33 .Fa "struct timespec *ts"
  34 .Fc
  35 .Sh DESCRIPTION
  36 The
  37 .Vt timeval
  38 and
  39 .Vt timespec
  40 structures are declared in the
  41 .In time.h
  42 and
  43 .In sys/time.h
  44 headers respectively:
  45 .Bd -literal -offset indent
  46 typedef struct timespec {
  47         time_t          tv_sec;         /* seconds */
  48         long            tv_nsec;        /* and nanoseconds */
  49 } timespec_t;
  50 
  51 struct timeval {
  52         time_t          tv_sec;         /* seconds */
  53         suseconds_t     tv_usec;        /* and microseconds */
  54 };
  55 .Ed
  56 .Pp
  57 In both cases, the
  58 .Fa tv_sec
  59 member represents elapsed time in whole seconds.
  60 The
  61 .Fa tv_nsec
  62 and
  63 .Fa tv_usec
  64 members represent the rest of the elapsed time in nanoseconds and
  65 microseconds respectively, depending on the structure.
  66 .Pp
  67 The
  68 .Dv TIMEVAL_TO_TIMESPEC
  69 macro can be used to convert a
  70 .Vt struct timeval
  71 structure to a
  72 .Vt struct timespec
  73 structure, while the
  74 .Dv TIMESPEC_TO_TIMEVAL
  75 macro works in the opposite direction.
  76 .Pp
  77 When converting from a
  78 .Vt struct timespec
  79 to a
  80 .Vt struct timeval
  81 structure, the
  82 .Fa tv_nsec
  83 member is truncated, losing precision.
  84 When converting from a
  85 .Vt struct timeval
  86 to a
  87 .Vt struct timespec
  88 structure, the
  89 .Fa tv_usec
  90 member is multiplied by 1000 to reach the precision of the target
  91 structure.
  92 The
  93 .Fa tv_sec
  94 member is always preserved, no matter which conversion is performed.
  95 .Pp
  96 Note that the
  97 .Dv TIMEVAL_TO_TIMESPEC
  98 and
  99 .Dv TIMESPEC_TO_TIMEVAL
 100 macros are non-standard but are commonly found on UNIX and UNIX-like systems.
 101 .Sh INTERFACE STABILITY
 102 .Sy Committed
 103 .Sh MT-LEVEL
 104 .Sy MT-Safe
 105 .Sh SEE ALSO
 106 .Xr time.h 3HEAD