lib/libc/sys/timer_settime.2

   1 .\"     $NetBSD: timer_settime.2,v 1.6 2010/05/17 07:22:03 jruoho 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 May 17, 2010
  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 (see
  56 .Xr itimerspec 3 )
  57 specified in the
  58 .Ar tim
  59 argument.
  60 If the value is 0, the timer is disarmed.
  61 If the argument
  62 .Ar otim
  63 is not
  64 .Dv NULL
  65 the old timer settingas are returned.
  66 .Pp
  67 If the
  68 .Ar flags
  69 argument is set to
  70 .Dv TIMER_RELTIME
  71 then the expiration time is set to the value in nanoseconds specified
  72 in the
  73 .Ar tim
  74 argument from the time the call to
  75 .Fn timer_settime
  76 was made.
  77 If the
  78 .Ar flags
  79 argument is set to
  80 .Dv TIMER_ABSTIME
  81 then the expiration time is set to be equal to the difference between the
  82 clock associated with this timer, and the value specified in the
  83 .Ar tim
  84 argument.
  85 If that time has already passed, then the call succeeds, and the
  86 expiration notification occurs.
  87 .Pp
  88 If the
  89 .Fa it_interval
  90 of the
  91 .Ar tim
  92 argument is non-zero, then the timer reloads upon expiration.
  93 .Pp
  94 The
  95 .Fn timer_gettime
  96 function returns the current settings of the timer
  97 specified by the
  98 .Ar timerid
  99 argument in the
 100 .Ar tim
 101 argument.
 102 .Pp
 103 Only one notification event (signal) can be pending for a given timer
 104 and process.
 105 If a timer expires while the signal is still queued for delivery, then
 106 the overrun counter for that timer is increased.
 107 The counter can store values up to
 108 .Dv DELAYTIMER_MAX .
 109 When the signal is finally delivered to the process, then the
 110 .Fn timer_getoverrun
 111 function can be used to retrieve the overrun counter for the timer
 112 specified in the
 113 .Ar timerid
 114 argument.
 115 .Sh NOTES
 116 Expiration time values are always rounded up to the resolution of the timer,
 117 so a notification will never be sent before the requested time.
 118 Values returned in the
 119 .Ar otim
 120 argument of
 121 .Fn timer_settime
 122 or in the
 123 .Ar tim
 124 argment of
 125 .Fn timer_gettime
 126 are subject to the above rounding effect and might not exactly match the
 127 requested values by the user.
 128 .Sh RETURN VALUES
 129 If successful, the
 130 .Fn timer_gettime
 131 and
 132 .Fn timer_settime
 133 functions return 0, and the
 134 .Fn timer_getoverrun
 135 function returns the expiration overrun count for the specified timer.
 136 Otherwise, the functions return \-1, and set
 137 .Dv errno
 138 to indicate the error.
 139 .Sh ERRORS
 140 The
 141 .Fn timer_gettime ,
 142 .Fn timer_getoverrun ,
 143 and
 144 .Fn timer_settime
 145 functions will fail if:
 146 .Bl -tag -width Er
 147 .It Bq Er EINVAL
 148 The argument
 149 .Ar timerid
 150 does not correspond to a valid timer id as returned by
 151 .Fn timer_create
 152 or that timer id has been deleted by
 153 .Fn timer_delete .
 154 .El
 155 .Pp
 156 The
 157 .Fn timer_settime
 158 function will fail if:
 159 .Bl -tag -width Er
 160 .It Bq Er EINVAL
 161 A nanosecond field in the
 162 .Ar tim
 163 structure specified a value less than zero or greater than or equal to 10e9.
 164 .El
 165 .Sh SEE ALSO
 166 .Xr clock_gettime 2 ,
 167 .Xr timer_create 2 ,
 168 .Xr timer_delete 2
 169 .Sh STANDARDS
 170 .St -p1003.1b-93 ,
 171 .St -p1003.1i-95