lib/libc/sys/timer_settime.2

   1 .\"     $NetBSD: timer_settime.2,v 1.4 2003/09/14 09:02:50 wiz Exp $
   2 .\"
   3 .\" Copyright (c) 2003 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Christos Zoulas.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd September 13, 2003
  31 .Dt TIMER_SETTIME 2
  32 .Os
  33 .Sh NAME
  34 .Nm timer_settime ,
  35 .Nm timer_gettime ,
  36 .Nm timer_getoverrun
  37 .Nd process timer manipulation
  38 .Sh LIBRARY
  39 .Lb libc
  40 .Sh SYNOPSIS
  41 .In time.h
  42 .Ft int
  43 .Fn timer_settime "timer_t timerid" "int flags" "const struct itimerspec * restrict tim" "struct itimerspec * restrict otim"
  44 .Ft int
  45 .Fn timer_gettime "timer_t timerid" "struct itimerspec *tim"
  46 .Ft int
  47 .Fn timer_getoverrun "timer_t timerid"
  48 .Sh DESCRIPTION
  49 The
  50 .Fn timer_settime
  51 sets the next expiration time of the timer with id
  52 .Ar timerid
  53 to the
  54 .Fa it_value
  55 specified in the
  56 .Ar tim
  57 argument.
  58 If the value is 0, the timer is disarmed.
  59 If the argument
  60 .Ar otim
  61 is not
  62 .Dv NULL
  63 the old timer settingas are returned.
  64 If the
  65 .Ar flags
  66 argument is set to
  67 .Dv TIMER_RELTIME
  68 then the expiration time is set to the value in nanoseconds specified
  69 in the
  70 .Ar tim
  71 argument from the time the call to
  72 .Fn timer_settime
  73 was made.
  74 If the
  75 .Ar flags
  76 argument is set to
  77 .Dv TIMER_ABSTIME
  78 then the expiration time is set to be equal to the difference between the
  79 clock associated with this timer, and the value specified in the
  80 .Ar tim
  81 argument.
  82 If that time has already passed, then the call succeeds, and the
  83 expiration notification occurs.
  84 .Pp
  85 If the
  86 .Fa it_interval
  87 of the
  88 .Ar tim
  89 argument is non-zero, then the timer reloads upon expiration.
  90 .Pp
  91 The
  92 .Fn timer_gettime
  93 function returns the current settings of the timer
  94 specified by the
  95 .Ar timerid
  96 argument in the
  97 .Ar tim
  98 argument.
  99 .Pp
 100 Only one notification event (signal) can be pending for a given timer
 101 and process.
 102 If a timer expires while the signal is still queued for delivery, then
 103 the overrun counter for that timer is increased.
 104 The counter can store values up to
 105 .Dv DELAYTIMER_MAX .
 106 When the signal is finally delivered to the process, then the
 107 .Fn timer_getoverrun
 108 function can be used to retrieve the overrun counter for the timer
 109 specified in the
 110 .Ar timerid
 111 argument.
 112 .Sh NOTES
 113 Expiration time values are always rounded up to the resolution of the timer,
 114 so a notification will never be sent before the requested time.
 115 Values returned in the
 116 .Ar otim
 117 argument of
 118 .Fn timer_settime
 119 or in the
 120 .Ar tim
 121 argment of
 122 .Fn timer_gettime
 123 are subject to the above rounding effect and might not exactly match the
 124 requested values by the user.
 125 .Sh RETURN VALUES
 126 If successful, the
 127 .Fn timer_gettime
 128 and
 129 .Fn timer_settime
 130 functions return 0, and the
 131 .Fn timer_getoverrun
 132 function returns the expiration overrun count for the specified timer.
 133 Otherwise, the functions return \-1, and set
 134 .Dv errno
 135 to indicate the error.
 136 .Sh ERRORS
 137 The
 138 .Fn timer_gettime ,
 139 .Fn timer_getoverrun ,
 140 and
 141 .Fn timer_settime
 142 functions will fail if:
 143 .Bl -tag -width Er
 144 .It Bq Er EINVAL
 145 The argument
 146 .Ar timerid
 147 does not correspond to a valid timer id as returned by
 148 .Fn timer_create
 149 or that timer id has been deleted by
 150 .Fn timer_delete .
 151 .El
 152 .Pp
 153 The
 154 .Fn timer_settime
 155 function will fail if:
 156 .Bl -tag -width Er
 157 .It Bq Er EINVAL
 158 A nanosecond field in the
 159 .Ar tim
 160 structure specified a value less than zero or greater than or equal to 10e9.
 161 .El
 162 .Sh SEE ALSO
 163 .Xr clock_gettime 2 ,
 164 .Xr timer_create 2 ,
 165 .Xr timer_delete 2
 166 .Sh STANDARDS
 167 .St -p1003.1b-93 ,
 168 .St -p1003.1i-95