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 .\"     @(#)getitimer.2 8.3 (Berkeley) 5/16/95
  29 .\"
  30 .Dd May 1, 2020
  31 .Dt GETITIMER 2
  32 .Os
  33 .Sh NAME
  34 .Nm getitimer ,
  35 .Nm setitimer
  36 .Nd get/set value of interval timer
  37 .Sh LIBRARY
  38 .Lb libc
  39 .Sh SYNOPSIS
  40 .In sys/time.h
  41 .Fd "#define ITIMER_REAL      0"
  42 .Fd "#define ITIMER_VIRTUAL   1"
  43 .Fd "#define ITIMER_PROF      2"
  44 .Ft int
  45 .Fn getitimer "int which" "struct itimerval *value"
  46 .Ft int
  47 .Fn setitimer "int which" "const struct itimerval *value" "struct itimerval *ovalue"
  48 .Sh DESCRIPTION
  49 The system provides each process with three interval timers,
  50 defined in
  51 .In sys/time.h .
  52 The
  53 .Fn getitimer
  54 system call returns the current value for the timer specified in
  55 .Fa which
  56 in the structure at
  57 .Fa value .
  58 The
  59 .Fn setitimer
  60 system call sets a timer to the specified
  61 .Fa value
  62 (returning the previous value of the timer if
  63 .Fa ovalue
  64 is not a null pointer).
  65 .Pp
  66 A timer value is defined by the
  67 .Fa itimerval
  68 structure:
  69 .Bd -literal -offset indent
  70 struct itimerval {
  71         struct  timeval it_interval;    /* timer interval */
  72         struct  timeval it_value;       /* current value */
  73 };
  74 .Ed
  75 .Pp
  76 If
  77 .Fa it_value
  78 is non-zero, it indicates the time to the next timer expiration.
  79 If
  80 .Fa it_interval
  81 is non-zero, it specifies a value to be used in reloading
  82 .Fa it_value
  83 when the timer expires.
  84 Setting
  85 .Fa it_value
  86 to 0 disables a timer, regardless of the value of
  87 .Fa it_interval .
  88 Setting
  89 .Fa it_interval
  90 to 0 causes a timer to be disabled after its next expiration (assuming
  91 .Fa it_value
  92 is non-zero).
  93 .Pp
  94 Time values smaller than the resolution of the
  95 system clock are rounded up to this resolution
  96 (typically 10 milliseconds).
  97 .Pp
  98 The
  99 .Dv ITIMER_REAL
 100 timer decrements in real time.
 101 A
 102 .Dv SIGALRM
 103 signal is
 104 delivered when this timer expires.
 105 .Pp
 106 The
 107 .Dv ITIMER_VIRTUAL
 108 timer decrements in process virtual time.
 109 It runs only when the process is executing.
 110 A
 111 .Dv SIGVTALRM
 112 signal
 113 is delivered when it expires.
 114 .Pp
 115 The
 116 .Dv ITIMER_PROF
 117 timer decrements both in process virtual time and
 118 when the system is running on behalf of the process.
 119 It is designed
 120 to be used by interpreters in statistically profiling the execution
 121 of interpreted programs.
 122 Each time the
 123 .Dv ITIMER_PROF
 124 timer expires, the
 125 .Dv SIGPROF
 126 signal is
 127 delivered.
 128 Because this signal may interrupt in-progress
 129 system calls, programs using this timer must be prepared to
 130 restart interrupted system calls.
 131 .Pp
 132 The maximum number of seconds allowed for
 133 .Fa it_interval
 134 and
 135 .Fa it_value
 136 in
 137 .Fn setitimer
 138 is 100000000.
 139 .Sh NOTES
 140 Three macros for manipulating time values are defined in
 141 .In sys/time.h .
 142 The
 143 .Fn timerclear
 144 macro
 145 sets a time value to zero,
 146 .Fn timerisset
 147 tests if a time value is non-zero, and
 148 .Fn timercmp
 149 compares two time values.
 150 .Sh RETURN VALUES
 151 .Rv -std
 152 .Sh ERRORS
 153 The
 154 .Fn getitimer
 155 and
 156 .Fn setitimer
 157 system calls
 158 will fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EFAULT
 161 The
 162 .Fa value
 163 argument specified a bad address.
 164 .It Bq Er EINVAL
 165 The
 166 .Fa value
 167 argument specified a time that was too large
 168 to be handled.
 169 .El
 170 .Sh SEE ALSO
 171 .Xr gettimeofday 2 ,
 172 .Xr select 2 ,
 173 .Xr sigaction 2 ,
 174 .Xr clocks 7
 175 .Sh STANDARDS
 176 The
 177 .Fn getitimer
 178 and
 179 .Fn setitimer
 180 functions conform to
 181 .St -p1003.1-2001 .
 182 The later
 183 .St -p1003.1-2008
 184 revision however marked both functions as obsolescent,
 185 recommending the use of
 186 .Xr timer_gettime 2
 187 and
 188 .Xr timer_settime 2
 189 instead.
 190 .Sh HISTORY
 191 The
 192 .Fn getitimer
 193 system call appeared in
 194 .Bx 4.2 .