1.\" $OpenBSD: timeout.9,v 1.15 2001/07/17 02:32:51 krw 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. Redistributions in binary form must reproduce the above copyright 13.\" notice, this list of conditions and the following disclaimer in the 14.\" documentation and/or other materials provided with the distribution. 15.\" 3. The name of the author may not be used to endorse or promote products 16.\" derived from this software without specific prior written permission. 17.\" 18.\" THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, 19.\" INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY 20.\" AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL 21.\" THE AUTHOR BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, 22.\" EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, 23.\" PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; 24.\" OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, 25.\" WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR 26.\" OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF 27.\" ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 28.\" 29.Dd June 23, 1996 30.Dt TIMEOUT 9 31.Os 32.Sh NAME 33.Nm timeout_set , 34.Nm timeout_add , 35.Nm timeout_del , 36.Nm timeout_pending , 37.Nm timeout_initialized 38.Nd execute a function after a specified period of time 39.Sh SYNOPSIS 40.Fd #include <sys/types.h> 41.Fd #include <sys/timeout.h> 42.Ft void 43.Fn "timeout_set" "struct timeout *to" "void (*fn)(void *)" "void *arg" 44.Ft void 45.Fn "timeout_add" "struct timeout *to" "int ticks" 46.Ft void 47.Fn "timeout_del" "struct timeout *to" 48.Ft int 49.Fn "timeout_pending" "struct timeout *to" 50.Ft int 51.Fn "timeout_initialized" "struct timeout *to" 52.Ft int 53.Fn "timeout_triggered" "struct timeout *to" 54.Sh DESCRIPTION 55The 56.Nm timeout 57API provides a mechanism to execute a function at a given time. 58The granularity of the time is limited by the granularity of the 59.Xr hardclock 9 60timer which executes 61.Nm hz 62times a second. 63The function will be called at softclock interrupt level. 64.Pp 65It is the responsibility of the caller to provide these functions with 66pre-allocated timeout structures. 67All functions in this API may be used in interrupt context below 68.Fn splclock . 69.Pp 70This API replaces the historic functions 71.Fn timeout 72and 73.Fn untimeout . 74.Pp 75The function 76.Fn timeout_set 77prepares the timeout structure 78.Fa to 79to be used in future calls to 80.Fn timeout_add 81and 82.Fn timeout_del . 83The timeout will be prepared to call the function specified by the 84.Fa fn 85argument with a 86.Fa void * 87argument given in the 88.Fa arg 89argument. 90Once initialized, the 91.Fa to 92structure can be used in repeatedly in 93.Fn timeout_add 94and 95.Fn timeout_del 96and does not need to be reinitialized unless you wish to 97change the function called and/or the argument to it. 98.Pp 99The function 100.Fn timeout_add 101schedules the execution of the 102.Fa to 103timeout in at least 104.Fa ticks Ns No /hz 105seconds. 106Negative values of 107.Fa ticks 108are illegal. 109If the value is 110.Sq 0 111it will, in the current implementation, be treated as 112.Sq 1 , 113but in the future it might cause an immediate timeout. 114The timeout in the 115.Fa to 116argument must be already initialized by 117.Fn timeout_set 118and may not be used in calls to 119.Fn timeout_set 120until it has timed out or been removed with 121.Fn timeout_del . 122If the timeout in the 123.Fa to 124argument is already scheduled, the old execution time will be 125replaced by the new one. 126.Pp 127The function 128.Fn timeout_del 129will cancel the timeout in the argument 130.Fa to . 131If the timeout has already executed or has never been added 132the call will have no effect. 133.Pp 134The 135.Fn timeout_pending 136macro can be used to check if a timeout is scheduled to run. 137.Pp 138The 139.Fn timeout_initialized 140macro can be used to check if a timeout has been initialized. 141.Pp 142The 143.Fn timeout_triggered 144macro can be used to check if a timeout is running or has been run. 145The 146.Fn timeout_add 147and 148.Fn timeout_del 149functions clear the triggered state for that timeout. 150.Pp 151The old 152.Fn timeout 153and 154.Fn untimeout 155interface is implemented as wrappers around the new API, but it's 156obsolete and will be removed in the future. 157.Sh CODE REFERENCES 158These functions are implemented in the file 159.Pa sys/kern/kern_timeout.c . 160.Sh SEE ALSO 161.Xr hz 9 , 162.Xr hzto 9 , 163.Xr sleep 9 , 164.Xr splclock 9 165.Sh BUGS 166The 167.Fn timeout_add 168function executes in linear time depending on the number of pending timeouts. 169It will also block all interrupts while inserting the timeout 170to the timeout queue. 171Thus it is not recommended to use a large number of timeouts in the system. 172