1.\" $OpenBSD: timeout.9,v 1.28 2008/07/30 19:41:32 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: July 30 2008 $ 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_nsec , 34.Nm timeout_add_usec , 35.Nm timeout_add_tv , 36.Nm timeout_add_ts , 37.Nm timeout_add_bt , 38.Nm timeout_del , 39.Nm timeout_pending , 40.Nm timeout_initialized , 41.Nm timeout_triggered 42.Nd execute a function after a specified period of time 43.Sh SYNOPSIS 44.Fd #include <sys/types.h> 45.Fd #include <sys/timeout.h> 46.Ft void 47.Fn "timeout_set" "struct timeout *to" "void (*fn)(void *)" "void *arg" 48.Ft void 49.Fn "timeout_add" "struct timeout *to" "int ticks" 50.Ft void 51.Fn "timeout_del" "struct timeout *to" 52.Ft int 53.Fn "timeout_pending" "struct timeout *to" 54.Ft int 55.Fn "timeout_initialized" "struct timeout *to" 56.Ft int 57.Fn "timeout_triggered" "struct timeout *to" 58.Ft void 59.Fn "timeout_add_tv" "struct timeout *to" "struct timeval *" 60.Ft void 61.Fn "timeout_add_ts" "struct timeout *to" "struct timespec *" 62.Ft void 63.Fn "timeout_add_bt" "struct timeout *to" "struct bintime *" 64.Ft void 65.Fn "timeout_add_sec" "struct timeout *to" "int sec" 66.Ft void 67.Fn "timeout_add_usec" "struct timeout *to" "int usec" 68.Ft void 69.Fn "timeout_add_nsec" "struct timeout *to" "int nsec" 70.Sh DESCRIPTION 71The 72.Nm timeout 73API provides a mechanism to execute a function at a given time. 74The granularity of the time is limited by the granularity of the 75.Xr hardclock 9 76timer which executes 77.Xr hz 9 78times a second. 79The function will be called at softclock interrupt level. 80.Pp 81It is the responsibility of the caller to provide these functions with 82pre-allocated timeout structures. 83All functions in this API may be used in interrupt context below 84.Fn splclock . 85.Pp 86This API replaces the historic functions 87.Fn timeout 88and 89.Fn untimeout . 90.Pp 91The function 92.Fn timeout_set 93prepares the timeout structure 94.Fa to 95to be used in future calls to 96.Fn timeout_add 97and 98.Fn timeout_del . 99The timeout will be prepared to call the function specified by the 100.Fa fn 101argument with a 102.Fa void * 103argument given in the 104.Fa arg 105argument. 106Once initialized, the 107.Fa to 108structure can be used repeatedly in 109.Fn timeout_add 110and 111.Fn timeout_del 112and does not need to be reinitialized unless 113the function called and/or its argument must change. 114.Pp 115The function 116.Fn timeout_add 117schedules the execution of the 118.Fa to 119timeout in at least 120.Fa ticks Ns /hz 121seconds. 122Negative values of 123.Fa ticks 124are illegal. 125If the value is 126.Sq 0 127it will, in the current implementation, be treated as 128.Sq 1 , 129but in the future it might cause an immediate timeout. 130The timeout in the 131.Fa to 132argument must be already initialized by 133.Fn timeout_set 134and may not be used in calls to 135.Fn timeout_set 136until it has timed out or been removed with 137.Fn timeout_del . 138If the timeout in the 139.Fa to 140argument is already scheduled, the old execution time will be 141replaced by the new one. 142.Pp 143The function 144.Fn timeout_del 145will cancel the timeout in the argument 146.Fa to . 147If the timeout has already executed or has never been added 148the call will have no effect. 149.Pp 150The 151.Fn timeout_pending 152macro can be used to check if a timeout is scheduled to run. 153.Pp 154The 155.Fn timeout_initialized 156macro can be used to check if a timeout has been initialized. 157.Pp 158The 159.Fn timeout_triggered 160macro can be used to check if a timeout is running or has been run. 161The 162.Fn timeout_add 163and 164.Fn timeout_del 165functions clear the triggered state for that timeout. 166.Pp 167When possible, use the 168.Fn timeout_add_tv , 169.Fn timeout_add_ts , 170.Fn timeout_add_bt , 171.Fn timeout_add_sec , 172.Fn timeout_add_usec , 173and 174.Fn timeout_add_nsec 175functions instead of 176.Fn timeout_add . 177Those functions add a timeout whilst converting the time specified 178by the respective types. 179.Sh CODE REFERENCES 180These functions are implemented in the file 181.Pa sys/kern/kern_timeout.c . 182.Sh SEE ALSO 183.Xr hz 9 , 184.Xr hzto 9 , 185.Xr splclock 9 , 186.Xr tsleep 9 , 187.Xr tvtohz 9 188