1.\" Copyright (c) 2005 David Xu <[email protected]> 2.\" 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(s), this list of conditions and the following disclaimer as 9.\" the first lines of this file unmodified other than the possible 10.\" addition of one or more copyright notices. 11.\" 2. Redistributions in binary form must reproduce the above copyright 12.\" notice(s), this list of conditions and the following disclaimer in 13.\" the documentation and/or other materials provided with the 14.\" distribution. 15.\" 16.\" THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER(S) ``AS IS'' AND ANY 17.\" EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 18.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 19.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER(S) BE 20.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 21.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 22.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR 23.\" BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 24.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE 25.\" OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, 26.\" EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 27.\" 28.\" $FreeBSD$ 29.\" 30.Dd September 11, 2000 31.Dt TIMER_SETTIME 2 32.Os 33.Sh NAME 34.Nm timer_getoverrun , 35.Nm timer_gettime , 36.Nm timer_settime 37.Nd "per-process timers (REALTIME)" 38.Sh LIBRARY 39.Lb librt 40.Sh SYNOPSIS 41.In time.h 42.Ft int 43.Fn timer_getoverrun "timer_t timerid" 44.Ft int 45.Fn timer_gettime "timer_t timerid" "struct itimerspec *value" 46.Ft int 47.Fo timer_settime 48.Fa "timer_t timerid" "int flags" "const struct itimerspec *restrict value" 49.Fa "struct itimerspec *restrict ovalue" 50.Fc 51.Sh DESCRIPTION 52The 53.Fn timer_gettime 54system call stores the amount of time until the specified timer, 55.Fa timerid , 56expires and the reload value of the timer into the space pointed to by the 57.Fa value 58argument. 59The 60.Va it_value 61member of this structure contains the amount of time 62before the timer expires, or zero if the timer is disarmed. 63This value is 64returned as the interval until timer expiration, even if the timer was armed 65with absolute time. 66The 67.Va it_interval 68member of 69.Fa value 70contains the reload 71value last set by 72.Fn timer_settime . 73.Pp 74The 75.Fn timer_settime 76system call sets the time until the next expiration of the timer specified 77by 78.Fa timerid 79from the 80.Va it_value 81member of the 82.Fa value 83argument and arms the timer if the 84.Va it_value 85member of 86.Fa value 87is non-zero. 88If the specified timer was already 89armed when 90.Fn timer_settime 91is called, this call resets the time until next expiration to the value 92specified. 93If the 94.Va it_value 95member of 96.Fa value 97is zero, the timer is disarmed. 98If the timer is disarmed, then pending signal is removed. 99.Pp 100If the flag 101.Dv TIMER_ABSTIME 102is not set in the argument 103.Fa flags , 104.Fn timer_settime 105behaves as if the time until next expiration is set to 106be equal to the interval specified by the 107.Va it_value 108member of 109.Fa value . 110That is, 111the timer expires in 112.Va it_value 113nanoseconds from when the call is made. 114If the flag 115.Dv TIMER_ABSTIME 116is set in the argument 117.Fa flags , 118.Fn timer_settime 119behaves as if the time until next expiration is set to be equal to the 120difference between the absolute time specified by the it_value member of 121value and the current value of the clock associated with 122.Fa timerid . 123That is, the timer expires when the clock reaches the value specified by the 124.Va it_value 125member of 126.Fa value . 127If the specified time has already passed, the 128system call succeeds and the expiration notification is made. 129.Pp 130The reload value of the timer is set to the value specified by the 131.Va it_interval 132member of 133.Fa value . 134When a timer is armed with a non-zero 135.Va it_interval , 136a periodic 137(or repetitive) timer is specified. 138.Pp 139Time values that are between two consecutive non-negative integer multiples of 140the resolution of the specified timer are rounded up to the larger multiple of 141the resolution. 142Quantization error will not cause the timer to expire earlier 143than the rounded time value. 144.Pp 145If the argument 146.Fa ovalue 147is not 148.Dv NULL , 149the 150.Fn timer_settime 151system call stores, in the location referenced by 152.Fa ovalue , 153a value representing 154the previous amount of time before the timer would have expired, or zero if the 155timer was disarmed, together with the previous timer reload value. 156Timers do not 157expire before their scheduled time. 158.Pp 159Only a single signal is queued to the process for a given timer at any point in 160time. 161When a timer for which a signal is still pending expires, no signal is 162queued, and a timer overrun will occur. 163When a timer expiration signal is 164accepted by a process, the 165.Fn timer_getoverrun 166system call returns the timer expiration overrun count for the specified timer. 167The overrun count returned contains the number of extra timer expirations that 168occurred between the time the signal was generated (queued) and when it was 169accepted, up to but not including an maximum of 170.Brq Dv DELAYTIMER_MAX . 171If the number of 172such extra expirations is greater than or equal to 173.Brq Dv DELAYTIMER_MAX , 174then the overrun count is set to 175.Brq Dv DELAYTIMER_MAX . 176The value returned by 177.Fn timer_getoverrun 178applies to the most recent expiration signal acceptance for the timer. 179If no 180expiration signal has been delivered for the timer, the return value of 181.Fn timer_getoverrun 182is unspecified. 183.Sh RETURN VALUES 184If the 185.Fn timer_getoverrun 186system call succeeds, it returns the timer expiration overrun count as explained 187above. 188Otherwise the value \-1 is returned, and the global variable 189.Va errno 190is set to indicate the error. 191.Pp 192.Rv -std timer_gettime timer_settime 193.Sh ERRORS 194The 195.Fn timer_settime 196system call 197will fail if: 198.Bl -tag -width Er 199.It Bq Er EINVAL 200A 201.Fa value 202structure specified a nanosecond value less than zero or greater than 203or equal to 1000 million, and the 204.Va it_value 205member of that structure did not 206specify zero seconds and nanoseconds. 207.El 208.Pp 209These system calls may fail if: 210.Bl -tag -width Er 211.It Bq Er EINVAL 212The 213.Fa timerid 214argument does not correspond to an ID returned by 215.Fn timer_create 216but not yet deleted by 217.Fn timer_delete . 218.El 219.Pp 220The 221.Fn timer_settime 222system call may fail if: 223.Bl -tag -width Er 224.It Bq Er EINVAL 225The 226.Va it_interval 227member of 228.Fa value 229is not zero and the timer was created with 230notification by creation of a new thread 231.Va ( sigev_sigev_notify 232was 233.Dv SIGEV_THREAD ) 234and a fixed stack address has been set in the thread attribute pointed to by 235.Va sigev_notify_attributes . 236.El 237.Pp 238The 239.Fn timer_gettime 240and 241.Fn timer_settime 242system calls 243may fail if: 244.Bl -tag -width Er 245.It Bq Er EFAULT 246Any arguments point outside the allocated address space or there is a 247memory protection fault. 248.El 249.Sh SEE ALSO 250.Xr clock_getres 2 , 251.Xr timer_create 2 , 252.Xr siginfo 3 253.Sh STANDARDS 254The 255.Fn timer_getoverrun , 256.Fn timer_gettime , 257and 258.Fn timer_settime 259system calls conform to 260.St -p1003.1-2004 . 261.Sh HISTORY 262Support for 263.Tn POSIX 264per-process timer first appeared in 265.Fx 7.0 . 266