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