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