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