lib/libc/sys/getitimer.2

   1 .\"     $NetBSD: getitimer.2,v 1.21 2004/08/14 10:03:30 jdolecek Exp $
   2 .\"
   3 .\" Copyright (c) 1983, 1991, 1993
   4 .\"     The Regents of the University of California.  All rights reserved.
   5 .\"
   6 .\" Redistribution and use in source and binary forms, with or without
   7 .\" modification, are permitted provided that the following conditions
   8 .\" are met:
   9 .\" 1. Redistributions of source code must retain the above copyright
  10 .\"    notice, this list of conditions and the following disclaimer.
  11 .\" 2. Redistributions in binary form must reproduce the above copyright
  12 .\"    notice, this list of conditions and the following disclaimer in the
  13 .\"    documentation and/or other materials provided with the distribution.
  14 .\" 3. Neither the name of the University nor the names of its contributors
  15 .\"    may be used to endorse or promote products derived from this software
  16 .\"    without specific prior written permission.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  19 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  20 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  21 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  22 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  23 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  24 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  25 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  26 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  27 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  28 .\" SUCH DAMAGE.
  29 .\"
  30 .\"     @(#)getitimer.2 8.3 (Berkeley) 5/16/95
  31 .\"
  32 .Dd August 14, 2004
  33 .Dt GETITIMER 2
  34 .Os
  35 .Sh NAME
  36 .Nm getitimer ,
  37 .Nm setitimer
  38 .Nd get/set value of interval timer
  39 .Sh LIBRARY
  40 .Lb libc
  41 .Sh SYNOPSIS
  42 .In sys/time.h
  43 .Fd #define ITIMER_REAL         0
  44 .Fd #define ITIMER_VIRTUAL      1
  45 .Fd #define ITIMER_PROF         2
  46 .Ft int
  47 .Fn getitimer "int which" "struct itimerval *value"
  48 .Ft int
  49 .Fn setitimer "int which" "const struct itimerval * restrict value" "struct itimerval * restrict ovalue"
  50 .Sh DESCRIPTION
  51 The system provides each process with three interval timers,
  52 defined in
  53 .Ao Pa sys/time.h Ac .
  54 The
  55 .Fn getitimer
  56 call returns the current value for the timer specified in
  57 .Fa which
  58 in the structure at
  59 .Fa value .
  60 The
  61 .Fn setitimer
  62 call sets a timer to the specified
  63 .Fa value
  64 (returning the previous value of the timer if
  65 .Fa ovalue
  66 is non-nil).
  67 .Pp
  68 A timer value is defined by the
  69 .Fa itimerval
  70 structure:
  71 .Bd -literal -offset indent
  72 struct itimerval {
  73         struct  timeval it_interval;    /* timer interval */
  74         struct  timeval it_value;       /* current value */
  75 };
  76 .Ed
  77 .Pp
  78 If
  79 .Fa it_value
  80 is non-zero, it indicates the time to the next timer expiration.
  81 If
  82 .Fa it_interval
  83 is non-zero, it specifies a value to be used in reloading
  84 .Fa it_value
  85 when the timer expires.
  86 Setting
  87 .Fa it_value
  88 to 0 disables a timer.
  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 to be used by interpreters in statistically profiling
 121 the execution 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 .Sh NOTES
 132 Macros for manipulating time values are defined in
 133 .Ao Pa sys/time.h Ac .
 134 .Fn timerclear
 135 sets a time value to zero,
 136 .Fn timerisset
 137 tests if a time value is non-zero,
 138 .Fn timercmp
 139 compares two time values,
 140 .Fn timeradd
 141 adds a time value to another time value,
 142 .Fn timersub
 143 computes the time difference between two time values.
 144 .Sh RETURN VALUES
 145 If the calls succeed, a value of 0 is returned.
 146 If an error occurs, the value \-1 is returned, and a more precise error
 147 code is placed in the global variable
 148 .Va errno .
 149 .Sh ERRORS
 150 .Fn getitimer
 151 and
 152 .Fn setitimer
 153 will fail if:
 154 .Bl -tag -width Er
 155 .It Bq Er EFAULT
 156 The
 157 .Fa value
 158 parameter specified a bad address.
 159 .It Bq Er EINVAL
 160 A
 161 .Fa value
 162 parameter specified a time that was too large
 163 to be handled.
 164 .El
 165 .Sh SEE ALSO
 166 .Xr gettimeofday 2 ,
 167 .Xr poll 2 ,
 168 .Xr select 2 ,
 169 .Xr sigaction 2
 170 .Sh HISTORY
 171 The
 172 .Fn getitimer
 173 function call appeared in
 174 .Bx 4.2 .