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 .Pp
  46 .Fd #define ITIMER_REAL         0
  47 .Fd #define ITIMER_VIRTUAL      1
  48 .Fd #define ITIMER_PROF         2
  49 .Ft int
  50 .Fo getitimer
  51 .Fa "int which"
  52 .Fa "struct itimerval *value"
  53 .Fc
  54 .Ft int
  55 .Fo setitimer
  56 .Fa "int which"
  57 .Fa "const struct itimerval *restrict value"
  58 .Fa "struct itimerval *restrict ovalue"
  59 .Fc
  60 .Sh DESCRIPTION
  61 The system provides each process with three interval timers,
  62 defined in
  63 .Ao Pa sys/time.h Ac .
  64 The
  65 .Fn getitimer
  66 call returns the current value for the timer specified in
  67 .Fa which
  68 in the structure at
  69 .Fa value .
  70 The
  71 .Fn setitimer
  72 call sets a timer to the specified
  73 .Fa value
  74 (returning the previous value of the timer if
  75 .Fa ovalue
  76 is non-nil).
  77 .Pp
  78 A timer value is defined by the
  79 .Fa itimerval
  80 structure:
  81 .Bd -literal -offset indent
  82 struct itimerval {
  83         struct  timeval it_interval;    /* timer interval */
  84         struct  timeval it_value;       /* current value */
  85 };
  86 .Ed
  87 .Pp
  88 If
  89 .Fa it_value
  90 is non-zero, it indicates the time to the next timer expiration.
  91 If
  92 .Fa it_interval
  93 is non-zero, it specifies a value to be used in reloading
  94 .Fa it_value
  95 when the timer expires.
  96 Setting
  97 .Fa it_value
  98 to 0 disables a timer.  Setting
  99 .Fa it_interval
 100 to 0 causes a timer to be disabled after its next expiration (assuming
 101 .Fa it_value
 102 is non-zero).
 103 .Pp
 104 Time values smaller than the resolution of the
 105 system clock are rounded up to this resolution
 106 (typically 10 milliseconds).
 107 .Pp
 108 The
 109 .Dv ITIMER_REAL
 110 timer decrements in real time.  A
 111 .Dv SIGALRM
 112 signal is
 113 delivered when this timer expires.
 114 .Pp
 115 The
 116 .Dv ITIMER_VIRTUAL
 117 timer decrements in process virtual time.
 118 It runs only when the process is executing.  A
 119 .Dv SIGVTALRM
 120 signal
 121 is delivered when it expires.
 122 .Pp
 123 The
 124 .Dv ITIMER_PROF
 125 timer decrements both in process virtual time and
 126 when the system is running on behalf of the process.  It is designed
 127 to be used by interpreters in statistically profiling the execution
 128 of interpreted programs.
 129 Each time the
 130 .Dv ITIMER_PROF
 131 timer expires, the
 132 .Dv SIGPROF
 133 signal is
 134 delivered.  Because this signal may interrupt in-progress
 135 system calls, programs using this timer must be prepared to
 136 restart interrupted system calls.
 137 .Sh NOTES
 138 Three macros for manipulating time values are defined in
 139 .Ao Pa sys/time.h Ac .
 140 .Fa Timerclear
 141 sets a time value to zero,
 142 .Fa timerisset
 143 tests if a time value is non-zero, and
 144 .Fa timercmp
 145 compares two time values (beware that >= and <= do not
 146 work with this macro).
 147 .Sh RETURN VALUES
 148 Upon successful completion, a value of 0 is returned.
 149 Otherwise, a value of -1 is returned and the global integer variable
 150 .Va errno
 151 is set to indicate the error.
 152 .Sh ERRORS
 153 .Fn Getitimer
 154 and
 155 .Fn setitimer
 156 will fail if:
 157 .Bl -tag -width Er
 158 .\" ==========
 159 .It Bq Er EFAULT
 160 The
 161 .Fa value
 162 parameter specified a bad address.
 163 .\" ==========
 164 .It Bq Er EINVAL
 165 The
 166 .Fa value
 167 parameter specified a time that was too large to be handled
 168 or not in the canonical form.
 169 .\" ==========
 170 .It Bq Er EINVAL
 171 The
 172 .Fa which
 173 parameter was invalid.
 174 .El
 175 .Sh SEE ALSO
 176 .Xr gettimeofday 2 ,
 177 .Xr select 2 ,
 178 .Xr sigaction 2
 179 .Sh HISTORY
 180 The
 181 .Fn getitimer
 182 function call appeared in
 183 .Bx 4.2 .