man3/timeradd.3

   1 .\" Copyright (c) 2007 by Michael Kerrisk <mtk.manpages@gmail.com>
   2 .\"
   3 .\" %%%LICENSE_START(VERBATIM)
   4 .\" Permission is granted to make and distribute verbatim copies of this
   5 .\" manual provided the copyright notice and this permission notice are
   6 .\" preserved on all copies.
   7 .\"
   8 .\" Permission is granted to copy and distribute modified versions of this
   9 .\" manual under the conditions for verbatim copying, provided that the
  10 .\" entire resulting derived work is distributed under the terms of a
  11 .\" permission notice identical to this one.
  12 .\"
  13 .\" Since the Linux kernel and libraries are constantly changing, this
  14 .\" manual page may be incorrect or out-of-date.  The author(s) assume no
  15 .\" responsibility for errors or omissions, or for damages resulting from
  16 .\" the use of the information contained herein.  The author(s) may not
  17 .\" have taken the same level of care in the production of this manual,
  18 .\" which is licensed free of charge, as they might when working
  19 .\" professionally.
  20 .\"
  21 .\" Formatted or processed versions of this manual, if unaccompanied by
  22 .\" the source, must acknowledge the copyright and authors of this work.
  23 .\" %%%LICENSE_END
  24 .\"
  25 .\" 2007-07-31, mtk, Created
  26 .\"
  27 .TH TIMERADD 3 2017-09-15 "Linux" "Linux Programmer's Manual"
  28 .SH NAME
  29 timeradd, timersub, timercmp, timerclear, timerisset \- timeval operations
  30 .SH SYNOPSIS
  31 .nf
  32 .B #include <sys/time.h>
  33 .PP
  34 .BI "void timeradd(struct timeval *" a ", struct timeval *" b ,
  35 .BI "              struct timeval *" res );
  36 .PP
  37 .BI "void timersub(struct timeval *" a ", struct timeval *" b ,
  38 .BI "              struct timeval *" res );
  39 .PP
  40 .BI "void timerclear(struct timeval *" tvp );
  41 .PP
  42 .BI "int timerisset(struct timeval *" tvp );
  43 .PP
  44 .BI "int timercmp(struct timeval *" a ", struct timeval *" b ", " CMP );
  45 .fi
  46 .PP
  47 .in -4n
  48 Feature Test Macro Requirements for glibc (see
  49 .BR feature_test_macros (7)):
  50 .in
  51 .PP
  52 All functions shown above:
  53     Since glibc 2.19:
  54         _DEFAULT_SOURCE
  55     Glibc 2.19 and earlier:
  56         _BSD_SOURCE
  57 .SH DESCRIPTION
  58 The macros are provided to operate on
  59 .I timeval
  60 structures, defined in
  61 .I <sys/time.h>
  62 as:
  63 .PP
  64 .in +4n
  65 .EX
  66 struct timeval {
  67     time_t      tv_sec;     /* seconds */
  68     suseconds_t tv_usec;    /* microseconds */
  69 };
  70 .EE
  71 .in
  72 .PP
  73 .BR timeradd ()
  74 adds the time values in
  75 .I a
  76 and
  77 .IR b ,
  78 and places the sum in the
  79 .I timeval
  80 pointed to by
  81 .IR res .
  82 The result is normalized such that
  83 .I res\->tv_usec
  84 has a value in the range 0 to 999,999.
  85 .PP
  86 .BR timersub ()
  87 subtracts the time value in
  88 .I b
  89 from the time value in
  90 .IR a ,
  91 and places the result in the
  92 .I timeval
  93 pointed to by
  94 .IR res .
  95 The result is normalized such that
  96 .I res\->tv_usec
  97 has a value in the range 0 to 999,999.
  98 .PP
  99 .BR timerclear ()
 100 zeros out the
 101 .I timeval
 102 structure pointed to by
 103 .IR tvp ,
 104 so that it represents the Epoch: 1970-01-01 00:00:00 +0000 (UTC).
 105 .PP
 106 .BR timerisset ()
 107 returns true (nonzero) if either field of the
 108 .I timeval
 109 structure pointed to by
 110 .I tvp
 111 contains a nonzero value.
 112 .PP
 113 .BR timercmp ()
 114 compares the timer values in
 115 .I a
 116 and
 117 .I b
 118 using the comparison operator
 119 .IR CMP ,
 120 and returns true (nonzero) or false (0) depending on
 121 the result of the comparison.
 122 Some systems (but not Linux/glibc),
 123 have a broken
 124 .BR timercmp ()
 125 implementation,
 126 .\" HP-UX, Tru64, Irix have a definition like:
 127 .\"#define timercmp(tvp, uvp, cmp) \
 128 .\"    ((tvp)->tv_sec cmp (uvp)->tv_sec || \
 129 .\"    (tvp)->tv_sec == (uvp)->tv_sec && (tvp)->tv_usec cmp (uvp)->tv_usec)
 130 in which
 131 .I CMP
 132 of
 133 .IR >= ,
 134 .IR <= ,
 135 and
 136 .I ==
 137 do not work;
 138 portable applications can instead use
 139 .PP
 140     !timercmp(..., <)
 141     !timercmp(..., >)
 142     !timercmp(..., !=)
 143 .SH RETURN VALUE
 144 .BR timerisset ()
 145 and
 146 .BR timercmp ()
 147 return true (nonzero) or false (0).
 148 .SH ERRORS
 149 No errors are defined.
 150 .SH CONFORMING TO
 151 Not in POSIX.1.
 152 Present on most BSD derivatives.
 153 .SH SEE ALSO
 154 .BR gettimeofday (2),
 155 .BR time (7)