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