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: src/lib/libc/sys/getitimer.2,v 1.10.2.6 2001/12/14 18:34:00 ru Exp $
  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 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 call sets a timer to the specified
  66 .Fa value
  67 (returning the previous value of the timer if
  68 .Fa ovalue
  69 is non-nil).
  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.  A
 106 .Dv SIGALRM
 107 signal is
 108 delivered when this timer expires.
 109 .Pp
 110 The
 111 .Dv ITIMER_VIRTUAL
 112 timer decrements in process virtual time.
 113 It runs only when the process is executing.  A
 114 .Dv SIGVTALRM
 115 signal
 116 is delivered when it expires.
 117 .Pp
 118 The
 119 .Dv ITIMER_PROF
 120 timer decrements both in process virtual time and
 121 when the system is running on behalf of the process.  It is designed
 122 to be used by interpreters in statistically profiling the execution
 123 of interpreted programs.
 124 Each time the
 125 .Dv ITIMER_PROF
 126 timer expires, the
 127 .Dv SIGPROF
 128 signal is
 129 delivered.  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 .Fa Timerclear
 144 sets a time value to zero,
 145 .Fa timerisset
 146 tests if a time value is non-zero, and
 147 .Fa timercmp
 148 compares two time values.
 149 .Sh RETURN VALUES
 150 .Rv -std
 151 .Sh ERRORS
 152 .Fn Getitimer
 153 and
 154 .Fn setitimer
 155 will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er EFAULT
 158 The
 159 .Fa value
 160 parameter specified a bad address.
 161 .It Bq Er EINVAL
 162 A
 163 .Fa value
 164 parameter specified a time that was too large
 165 to be handled.
 166 .El
 167 .Sh SEE ALSO
 168 .Xr gettimeofday 2 ,
 169 .Xr select 2 ,
 170 .Xr sigaction 2 ,
 171 .Xr clocks 7
 172 .Sh HISTORY
 173 The
 174 .Fn getitimer
 175 function call appeared in
 176 .Bx 4.2 .