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