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 .\" $FreeBSD: src/lib/libc/sys/getitimer.2,v 1.10.2.6 2001/12/14 18:34:00 ru Exp $
  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 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 call sets a timer to the specified
  62 .Fa value
  63 (returning the previous value of the timer if
  64 .Fa ovalue
  65 is non-nil).
  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.  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.  A
 110 .Dv SIGVTALRM
 111 signal
 112 is delivered when it expires.
 113 .Pp
 114 The
 115 .Dv ITIMER_PROF
 116 timer decrements both in process virtual time and
 117 when the system is running on behalf of the process.  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.  Because this signal may interrupt in-progress
 126 system calls, programs using this timer must be prepared to
 127 restart interrupted system calls.
 128 .Pp
 129 The maximum number of seconds allowed for
 130 .Fa it_interval
 131 and
 132 .Fa it_value
 133 in
 134 .Fn setitimer
 135 is 100000000.
 136 .Sh NOTES
 137 Three macros for manipulating time values are defined in
 138 .In sys/time.h .
 139 .Fa Timerclear
 140 sets a time value to zero,
 141 .Fa timerisset
 142 tests if a time value is non-zero, and
 143 .Fa timercmp
 144 compares two time values.
 145 .Sh RETURN VALUES
 146 .Rv -std
 147 .Sh ERRORS
 148 .Fn Getitimer
 149 and
 150 .Fn setitimer
 151 will fail if:
 152 .Bl -tag -width Er
 153 .It Bq Er EFAULT
 154 The
 155 .Fa value
 156 parameter specified a bad address.
 157 .It Bq Er EINVAL
 158 A
 159 .Fa value
 160 parameter specified a time that was too large
 161 to be handled.
 162 .El
 163 .Sh SEE ALSO
 164 .Xr gettimeofday 2 ,
 165 .Xr select 2 ,
 166 .Xr sigaction 2 ,
 167 .Xr clocks 7
 168 .Sh HISTORY
 169 The
 170 .Fn getitimer
 171 function call appeared in
 172 .Bx 4.2 .