1.\" $OpenBSD: timeout.9,v 1.31 2011/05/10 01:03:28 dlg Exp $ 2.\" 3.\" Copyright (c) 2000 Artur Grabowski <art@openbsd.org> 4.\" All rights reserved. 5.\" 6.\" Redistribution and use in source and binary forms, with or without 7.\" modification, are permitted provided that the following conditions 8.\" are met: 9.\" 10.\" 1. Redistributions of source code must retain the above copyright 11.\" notice, this list of conditions and the following disclaimer. 12.\" 2. The name of the author may not be used to endorse or promote products 13.\" derived from this software without specific prior written permission. 14.\" 15.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 16.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 17.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 18.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 19.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 20.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 21.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 22.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 23.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 24.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 25.\" 26.Dd $Mdocdate: May 10 2011 $ 27.Dt TIMEOUT 9 28.Os 29.Sh NAME 30.Nm timeout_set , 31.Nm timeout_add , 32.Nm timeout_add_sec , 33.Nm timeout_add_msec , 34.Nm timeout_add_nsec , 35.Nm timeout_add_usec , 36.Nm timeout_add_tv , 37.Nm timeout_add_ts , 38.Nm timeout_add_bt , 39.Nm timeout_del , 40.Nm timeout_pending , 41.Nm timeout_initialized , 42.Nm timeout_triggered 43.Nd execute a function after a specified period of time 44.Sh SYNOPSIS 45.Fd #include <sys/types.h> 46.Fd #include <sys/timeout.h> 47.Ft void 48.Fn "timeout_set" "struct timeout *to" "void (*fn)(void *)" "void *arg" 49.Ft void 50.Fn "timeout_add" "struct timeout *to" "int ticks" 51.Ft int 52.Fn "timeout_del" "struct timeout *to" 53.Ft int 54.Fn "timeout_pending" "struct timeout *to" 55.Ft int 56.Fn "timeout_initialized" "struct timeout *to" 57.Ft int 58.Fn "timeout_triggered" "struct timeout *to" 59.Ft void 60.Fn "timeout_add_tv" "struct timeout *to" "struct timeval *" 61.Ft void 62.Fn "timeout_add_ts" "struct timeout *to" "struct timespec *" 63.Ft void 64.Fn "timeout_add_bt" "struct timeout *to" "struct bintime *" 65.Ft void 66.Fn "timeout_add_sec" "struct timeout *to" "int sec" 67.Ft void 68.Fn "timeout_add_msec" "struct timeout *to" "int msec" 69.Ft void 70.Fn "timeout_add_usec" "struct timeout *to" "int usec" 71.Ft void 72.Fn "timeout_add_nsec" "struct timeout *to" "int nsec" 73.Sh DESCRIPTION 74The 75.Nm timeout 76API provides a mechanism to execute a function at a given time. 77The granularity of the time is limited by the granularity of the 78.Xr hardclock 9 79timer which executes 80.Xr hz 9 81times a second. 82The function will be called at softclock interrupt level. 83.Pp 84It is the responsibility of the caller to provide these functions with 85pre-allocated timeout structures. 86All functions in this API may be used in interrupt context below 87.Fn splclock . 88.Pp 89The function 90.Fn timeout_set 91prepares the timeout structure 92.Fa to 93to be used in future calls to 94.Fn timeout_add 95and 96.Fn timeout_del . 97The timeout will be prepared to call the function specified by the 98.Fa fn 99argument with a 100.Fa void * 101argument given in the 102.Fa arg 103argument. 104Once initialized, the 105.Fa to 106structure can be used repeatedly in 107.Fn timeout_add 108and 109.Fn timeout_del 110and does not need to be reinitialized unless 111the function called and/or its argument must change. 112.Pp 113The function 114.Fn timeout_add 115schedules the execution of the 116.Fa to 117timeout in at least 118.Fa ticks Ns /hz 119seconds. 120Negative values of 121.Fa ticks 122are illegal. 123If the value is 124.Sq 0 125it will, in the current implementation, be treated as 126.Sq 1 , 127but in the future it might cause an immediate timeout. 128The timeout in the 129.Fa to 130argument must be already initialized by 131.Fn timeout_set 132and may not be used in calls to 133.Fn timeout_set 134until it has timed out or been removed with 135.Fn timeout_del . 136If the timeout in the 137.Fa to 138argument is already scheduled, the old execution time will be 139replaced by the new one. 140.Pp 141The function 142.Fn timeout_del 143will cancel the timeout in the argument 144.Fa to . 145If the timeout has already executed or has never been added 146the call will have no effect. 147If the timeout was actually removed by 148.Fn timeout_del 149it will return 1. 150.Pp 151The 152.Fn timeout_pending 153macro can be used to check if a timeout is scheduled to run. 154.Pp 155The 156.Fn timeout_initialized 157macro can be used to check if a timeout has been initialized. 158.Pp 159The 160.Fn timeout_triggered 161macro can be used to check if a timeout is running or has been run. 162The 163.Fn timeout_add 164and 165.Fn timeout_del 166functions clear the triggered state for that timeout. 167.Pp 168When possible, use the 169.Fn timeout_add_tv , 170.Fn timeout_add_ts , 171.Fn timeout_add_bt , 172.Fn timeout_add_sec , 173.Fn timeout_add_msec , 174.Fn timeout_add_usec , 175and 176.Fn timeout_add_nsec 177functions instead of 178.Fn timeout_add . 179Those functions add a timeout whilst converting the time specified 180by the respective types. 181.Sh CODE REFERENCES 182These functions are implemented in the file 183.Pa sys/kern/kern_timeout.c . 184.Sh SEE ALSO 185.Xr hz 9 , 186.Xr hzto 9 , 187.Xr splclock 9 , 188.Xr tsleep 9 , 189.Xr tvtohz 9 190