bsd/man/man2/getitimer.2

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