1.\" $OpenBSD: timeout.9,v 1.29 2009/04/21 19:30:14 mk 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: April 21 2009 $ 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 void 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 89This API replaces the historic functions 90.Fn timeout 91and 92.Fn untimeout . 93.Pp 94The function 95.Fn timeout_set 96prepares the timeout structure 97.Fa to 98to be used in future calls to 99.Fn timeout_add 100and 101.Fn timeout_del . 102The timeout will be prepared to call the function specified by the 103.Fa fn 104argument with a 105.Fa void * 106argument given in the 107.Fa arg 108argument. 109Once initialized, the 110.Fa to 111structure can be used repeatedly in 112.Fn timeout_add 113and 114.Fn timeout_del 115and does not need to be reinitialized unless 116the function called and/or its argument must change. 117.Pp 118The function 119.Fn timeout_add 120schedules the execution of the 121.Fa to 122timeout in at least 123.Fa ticks Ns /hz 124seconds. 125Negative values of 126.Fa ticks 127are illegal. 128If the value is 129.Sq 0 130it will, in the current implementation, be treated as 131.Sq 1 , 132but in the future it might cause an immediate timeout. 133The timeout in the 134.Fa to 135argument must be already initialized by 136.Fn timeout_set 137and may not be used in calls to 138.Fn timeout_set 139until it has timed out or been removed with 140.Fn timeout_del . 141If the timeout in the 142.Fa to 143argument is already scheduled, the old execution time will be 144replaced by the new one. 145.Pp 146The function 147.Fn timeout_del 148will cancel the timeout in the argument 149.Fa to . 150If the timeout has already executed or has never been added 151the call will have no effect. 152.Pp 153The 154.Fn timeout_pending 155macro can be used to check if a timeout is scheduled to run. 156.Pp 157The 158.Fn timeout_initialized 159macro can be used to check if a timeout has been initialized. 160.Pp 161The 162.Fn timeout_triggered 163macro can be used to check if a timeout is running or has been run. 164The 165.Fn timeout_add 166and 167.Fn timeout_del 168functions clear the triggered state for that timeout. 169.Pp 170When possible, use the 171.Fn timeout_add_tv , 172.Fn timeout_add_ts , 173.Fn timeout_add_bt , 174.Fn timeout_add_sec , 175.Fn timeout_add_msec , 176.Fn timeout_add_usec , 177and 178.Fn timeout_add_nsec 179functions instead of 180.Fn timeout_add . 181Those functions add a timeout whilst converting the time specified 182by the respective types. 183.Sh CODE REFERENCES 184These functions are implemented in the file 185.Pa sys/kern/kern_timeout.c . 186.Sh SEE ALSO 187.Xr hz 9 , 188.Xr hzto 9 , 189.Xr splclock 9 , 190.Xr tsleep 9 , 191.Xr tvtohz 9 192