man3/timeradd.3

   1 .\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
   4 .\"
   5 .\" 2007-07-31, mtk, Created
   6 .\"
   7 .TH timeradd 3 (date) "Linux man-pages (unreleased)"
   8 .SH NAME
   9 timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations
  10 .SH LIBRARY
  11 Standard C library
  12 .RI ( libc ", " \-lc )
  13 .SH SYNOPSIS
  14 .nf
  15 .B #include <sys/time.h>
  16 .PP
  17 .BI "void timeradd(struct timeval *" a ", struct timeval *" b ,
  18 .BI "              struct timeval *" res );
  19 .BI "void timersub(struct timeval *" a ", struct timeval *" b ,
  20 .BI "              struct timeval *" res );
  21 .PP
  22 .BI "void timerclear(struct timeval *" tvp );
  23 .BI "int timerisset(struct timeval *" tvp );
  24 .PP
  25 .BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP );
  26 .fi
  27 .PP
  28 .RS -4
  29 Feature Test Macro Requirements for glibc (see
  30 .BR feature_test_macros (7)):
  31 .RE
  32 .PP
  33 All functions shown above:
  34 .nf
  35     Since glibc 2.19:
  36         _DEFAULT_SOURCE
  37     Glibc 2.19 and earlier:
  38         _BSD_SOURCE
  39 .fi
  40 .SH DESCRIPTION
  41 The macros are provided to operate on
  42 .I timeval
  43 structures, defined in
  44 .I <sys/time.h>
  45 as:
  46 .PP
  47 .in +4n
  48 .EX
  49 struct timeval {
  50     time_t      tv_sec;     /* seconds */
  51     suseconds_t tv_usec;    /* microseconds */
  52 };
  53 .EE
  54 .in
  55 .PP
  56 .BR timeradd ()
  57 adds the time values in
  58 .I a
  59 and
  60 .IR b ,
  61 and places the sum in the
  62 .I timeval
  63 pointed to by
  64 .IR res .
  65 The result is normalized such that
  66 .I res\->tv_usec
  67 has a value in the range 0 to 999,999.
  68 .PP
  69 .BR timersub ()
  70 subtracts the time value in
  71 .I b
  72 from the time value in
  73 .IR a ,
  74 and places the result in the
  75 .I timeval
  76 pointed to by
  77 .IR res .
  78 The result is normalized such that
  79 .I res\->tv_usec
  80 has a value in the range 0 to 999,999.
  81 .PP
  82 .BR timerclear ()
  83 zeros out the
  84 .I timeval
  85 structure pointed to by
  86 .IR tvp ,
  87 so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC).
  88 .PP
  89 .BR timerisset ()
  90 returns true (nonzero) if either field of the
  91 .I timeval
  92 structure pointed to by
  93 .I tvp
  94 contains a nonzero value.
  95 .PP
  96 .BR timercmp ()
  97 compares the timer values in
  98 .I a
  99 and
 100 .I b
 101 using the comparison operator
 102 .IR CMP ,
 103 and returns true (nonzero) or false (0) depending on
 104 the result of the comparison.
 105 Some systems (but not Linux/glibc),
 106 have a broken
 107 .BR timercmp ()
 108 implementation,
 109 .\" HP-UX, Tru64, Irix have a definition like:
 110 .\"#define timercmp(tvp, uvp, cmp) \
 111 .\"    ((tvp)->tv_sec cmp (uvp)->tv_sec || \
 112 .\"    (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)
 113 in which
 114 .I CMP
 115 of
 116 .IR >= ,
 117 .IR <= ,
 118 and
 119 .I ==
 120 do not work;
 121 portable applications can instead use
 122 .PP
 123 .in +4n
 124 .EX
 125 !timercmp(..., <)
 126 !timercmp(..., >)
 127 !timercmp(..., !=)
 128 .EE
 129 .in
 130 .SH RETURN VALUE
 131 .BR timerisset ()
 132 and
 133 .BR timercmp ()
 134 return true (nonzero) or false (0).
 135 .SH ERRORS
 136 No errors are defined.
 137 .SH STANDARDS
 138 Not in POSIX.1.
 139 Present on most BSD derivatives.
 140 .SH SEE ALSO
 141 .BR gettimeofday (2),
 142 .BR time (7)