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