1.\" $NetBSD: timeout.9,v 1.2 1996/06/23 22:32:34 pk Exp $ 2.\" 3.\" Copyright (c) 1996 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Paul Kranenburg. 8.\" 9.\" Redistribution and use in source and binary forms, with or without 10.\" modification, are permitted provided that the following conditions 11.\" are met: 12.\" 1. Redistributions of source code must retain the above copyright 13.\" notice, this list of conditions and the following disclaimer. 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in the 16.\" documentation and/or other materials provided with the distribution. 17.\" 3. All advertising materials mentioning features or use of this software 18.\" must display the following acknowledgement: 19.\" This product includes software developed by the NetBSD 20.\" Foundation, Inc. and its contributors. 21.\" 4. Neither the name of The NetBSD Foundation nor the names of its 22.\" contributors may be used to endorse or promote products derived 23.\" from this software without specific prior written permission. 24.\" 25.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 26.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 27.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 28.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE 29.\" LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 30.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 31.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 32.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 33.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 34.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 35.\" POSSIBILITY OF SUCH DAMAGE. 36.\" 37.\" $FreeBSD: src/share/man/man9/timeout.9,v 1.9.2.6 2001/12/17 11:30:19 ru Exp $ 38.\" $DragonFly: src/share/man/man9/callout.9,v 1.6 2008/05/02 02:05:06 swildner Exp $ 39.\" 40.Dd November 14, 2007 41.Dt CALLOUT 9 42.Os 43.Sh NAME 44.Nm callout_init , 45.Nm callout_init_mp , 46.Nm callout_reset , 47.Nm callout_stop , 48.Nm callout_active , 49.Nm callout_pending , 50.Nm callout_deactivate 51.Nd execute a function after a specified length of time 52.Sh SYNOPSIS 53.In sys/types.h 54.In sys/systm.h 55.Bd -literal 56typedef void timeout_t (void *); 57.Ed 58.Ft void 59.Fn callout_init "struct callout *c" 60.Ft void 61.Fn callout_init_mp "struct callout *c" 62.Ft void 63.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" 64.Ft int 65.Fn callout_stop "struct callout *c" 66.Ft int 67.Fn callout_active "struct callout *c" 68.Ft int 69.Fn callout_pending "struct callout *c" 70.Fn callout_deactivate "struct callout *c" 71.Sh DESCRIPTION 72The 73.Nm callout 74facility provides a mechanism to execute a function at a given time. 75The timer is based on the hardclock timer which ticks 76.Dv hz 77times per second. 78.Pp 79Clients of the 80.Nm callout 81facility are responsible for providing pre-allocated callout structures, or 82.Dq handles . 83The 84.Nm callout 85facility replaces the historic 86.Bx 87functions 88.Fn timeout 89and 90.Fn untimeout . 91.Pp 92The 93.Fn callout_init 94function initializes the callout handle 95.Fa c 96so it can be passed to 97.Fn callout_stop 98or 99.Fn callout_reset 100without any side effects. 101The MP version of this function, 102.Fn callout_init_mp , 103requires that the callback function installed by 104.Fn callout_reset 105be MP safe. 106.Pp 107The 108.Fn callout_reset 109function resets and starts the timer associated with the callout handle 110.Fa c . 111When the timer expires after 112.Fa ticks Ns No /hz 113seconds, the function specified by 114.Fa func 115will be called with the argument 116.Fa arg . 117.Pp 118The function 119.Fn callout_stop 120cancels the callout associated with the callout handle 121.Fa c 122if it is currently pending. 123It is safe to call 124.Fn callout_stop 125on a callout that is not pending, so long as it is initialized. 126If the callout is not set, has already been serviced or is currently 127being serviced, then zero will be returned. 128.Pp 129The 130.Fn callout_pending 131macro tests if the callout handle 132.Fa c 133is pending. 134A pending callout is one that has been started and whose function has not 135yet been called. 136.Pp 137The 138.Fn callout_active 139macro returns true if a timer has been started but not explicitly stopped, 140even if it has already fired. 141.Pp 142The 143.Fn callout_deactivate 144macro deactivates the specified callout 145.Fa c . 146.Pp 147The 148.Fn callout_active , 149.Fn callout_pending 150and 151.Fn callout_deactivate 152macros may only be used when the state of the callout structure is stable, 153meaning from within the callback function or after the callback function 154has been called but the timer has not yet been reset. 155.Sh RETURN VALUES 156The 157.Fn callout_stop 158function and the 159.Fn callout_pending 160macro return non-zero if the callout is still pending or zero otherwise. 161The 162.Fn callout_active 163macro returns non-zero if the callout is active or zero otherwise. 164