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