lib/libc/sys/getitimer.2

   1 .\" Copyright (c) 1983, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" Redistribution and use in source and binary forms, with or without
   5 .\" modification, are permitted provided that the following conditions
   6 .\" are met:
   7 .\" 1. Redistributions of source code must retain the above copyright
   8 .\"    notice, this list of conditions and the following disclaimer.
   9 .\" 2. Redistributions in binary form must reproduce the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer in the
  11 .\"    documentation and/or other materials provided with the distribution.
  12 .\" 3. Neither the name of the University nor the names of its contributors
  13 .\"    may be used to endorse or promote products derived from this software
  14 .\"    without specific prior written permission.
  15 .\"
  16 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  17 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  18 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  19 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  20 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  21 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  22 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  23 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  24 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  25 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  26 .\" SUCH DAMAGE.
  27 .\"
  28 .Dd May 1, 2020
  29 .Dt GETITIMER 2
  30 .Os
  31 .Sh NAME
  32 .Nm getitimer ,
  33 .Nm setitimer
  34 .Nd get/set value of interval timer
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In sys/time.h
  39 .Fd "#define ITIMER_REAL      0"
  40 .Fd "#define ITIMER_VIRTUAL   1"
  41 .Fd "#define ITIMER_PROF      2"
  42 .Ft int
  43 .Fn getitimer "int which" "struct itimerval *value"
  44 .Ft int
  45 .Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue"
  46 .Sh DESCRIPTION
  47 The system provides each process with three interval timers,
  48 defined in
  49 .In sys/time.h .
  50 The
  51 .Fn getitimer
  52 system call returns the current value for the timer specified in
  53 .Fa which
  54 in the structure at
  55 .Fa value .
  56 The
  57 .Fn setitimer
  58 system call sets a timer to the specified
  59 .Fa value
  60 (returning the previous value of the timer if
  61 .Fa ovalue
  62 is not a null pointer).
  63 .Pp
  64 A timer value is defined by the
  65 .Fa itimerval
  66 structure:
  67 .Bd -literal -offset indent
  68 struct itimerval {
  69         struct  timeval it_interval;    /* timer interval */
  70         struct  timeval it_value;       /* current value */
  71 };
  72 .Ed
  73 .Pp
  74 If
  75 .Fa it_value
  76 is non-zero, it indicates the time to the next timer expiration.
  77 If
  78 .Fa it_interval
  79 is non-zero, it specifies a value to be used in reloading
  80 .Fa it_value
  81 when the timer expires.
  82 Setting
  83 .Fa it_value
  84 to 0 disables a timer, regardless of the value of
  85 .Fa it_interval .
  86 Setting
  87 .Fa it_interval
  88 to 0 causes a timer to be disabled after its next expiration (assuming
  89 .Fa it_value
  90 is non-zero).
  91 .Pp
  92 Time values smaller than the resolution of the
  93 system clock are rounded up to this resolution
  94 (typically 10 milliseconds).
  95 .Pp
  96 The
  97 .Dv ITIMER_REAL
  98 timer decrements in real time.
  99 A
 100 .Dv SIGALRM
 101 signal is
 102 delivered when this timer expires.
 103 .Pp
 104 The
 105 .Dv ITIMER_VIRTUAL
 106 timer decrements in process virtual time.
 107 It runs only when the process is executing.
 108 A
 109 .Dv SIGVTALRM
 110 signal
 111 is delivered when it expires.
 112 .Pp
 113 The
 114 .Dv ITIMER_PROF
 115 timer decrements both in process virtual time and
 116 when the system is running on behalf of the process.
 117 It is designed
 118 to be used by interpreters in statistically profiling the execution
 119 of interpreted programs.
 120 Each time the
 121 .Dv ITIMER_PROF
 122 timer expires, the
 123 .Dv SIGPROF
 124 signal is
 125 delivered.
 126 Because this signal may interrupt in-progress
 127 system calls, programs using this timer must be prepared to
 128 restart interrupted system calls.
 129 .Pp
 130 The maximum number of seconds allowed for
 131 .Fa it_interval
 132 and
 133 .Fa it_value
 134 in
 135 .Fn setitimer
 136 is 100000000.
 137 .Sh NOTES
 138 Three macros for manipulating time values are defined in
 139 .In sys/time.h .
 140 The
 141 .Fn timerclear
 142 macro
 143 sets a time value to zero,
 144 .Fn timerisset
 145 tests if a time value is non-zero, and
 146 .Fn timercmp
 147 compares two time values.
 148 .Sh RETURN VALUES
 149 .Rv -std
 150 .Sh ERRORS
 151 The
 152 .Fn getitimer
 153 and
 154 .Fn setitimer
 155 system calls
 156 will fail if:
 157 .Bl -tag -width Er
 158 .It Bq Er EFAULT
 159 The
 160 .Fa value
 161 argument specified a bad address.
 162 .It Bq Er EINVAL
 163 The
 164 .Fa value
 165 argument specified a time that was too large
 166 to be handled.
 167 .El
 168 .Sh SEE ALSO
 169 .Xr gettimeofday 2 ,
 170 .Xr select 2 ,
 171 .Xr sigaction 2 ,
 172 .Xr clocks 7
 173 .Sh STANDARDS
 174 The
 175 .Fn getitimer
 176 and
 177 .Fn setitimer
 178 functions conform to
 179 .St -p1003.1-2001 .
 180 The later
 181 .St -p1003.1-2008
 182 revision however marked both functions as obsolescent,
 183 recommending the use of
 184 .Xr timer_gettime 2
 185 and
 186 .Xr timer_settime 2
 187 instead.
 188 .Sh HISTORY
 189 The
 190 .Fn getitimer
 191 system call appeared in
 192 .Bx 4.2 .