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