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.5 2007/11/14 18:27:52 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.Pp 56.Bd -literal 57typedef void timeout_t (void *); 58.Ed 59.Ft void 60.Fn callout_init "struct callout *c" 61.Ft void 62.Fn callout_init_mp "struct callout *c" 63.Ft void 64.Fn callout_reset "struct callout *c" "int ticks" "timeout_t *func" "void *arg" 65.Ft int 66.Fn callout_stop "struct callout *c" 67.Ft int 68.Fn callout_active "struct callout *c" 69.Ft int 70.Fn callout_pending "struct callout *c" 71.Fn callout_deactivate "struct callout *c" 72.Sh DESCRIPTION 73The 74.Nm callout 75facility provides a mechanism to execute a function at a given time. 76The timer is based on the hardclock timer which ticks 77.Dv hz 78times per second. 79.Pp 80Clients of the 81.Nm callout 82facility are responsible for providing pre-allocated callout structures, or 83.Dq handles . 84The 85.Nm callout 86facility replaces the historic 87.Bx 88functions 89.Fn timeout 90and 91.Fn untimeout . 92.Pp 93The 94.Fn callout_init 95function initializes the callout handle 96.Fa c 97so it can be passed to 98.Fn callout_stop 99or 100.Fn callout_reset 101without any side effects. 102The MP version of this function, 103.Fn callout_init_mp , 104requires that the callback function installed by 105.Fn callout_reset 106be MP safe. 107.Pp 108The 109.Fn callout_reset 110function resets and starts the timer associated with the callout handle 111.Fa c . 112When the timer expires after 113.Fa ticks Ns No /hz 114seconds, the function specified by 115.Fa func 116will be called with the argument 117.Fa arg . 118.Pp 119The function 120.Fn callout_stop 121cancels the callout associated with the callout handle 122.Fa c 123if it is currently pending. 124It is safe to call 125.Fn callout_stop 126on a callout that is not pending, so long as it is initialized. 127If the callout is not set, has already been serviced or is currently 128being serviced, then zero will be returned. 129.Pp 130The 131.Fn callout_pending 132macro tests if the callout handle 133.Fa c 134is pending. 135A pending callout is one that has been started and whose function has not 136yet been called. 137.Pp 138The 139.Fn callout_active 140macro returns true if a timer has been started but not explicitly stopped, 141even if it has already fired. 142.Pp 143The 144.Fn callout_deactivate 145macro deactivates the specified callout 146.Fa c . 147.Pp 148The 149.Fn callout_active , 150.Fn callout_pending 151and 152.Fn callout_deactivate 153macros may only be used when the state of the callout structure is stable, 154meaning from within the callback function or after the callback function 155has been called but the timer has not yet been reset. 156.Sh RETURN VALUES 157The 158.Fn callout_stop 159function and the 160.Fn callout_pending 161macro return non-zero if the callout is still pending or zero otherwise. 162The 163.Fn callout_active 164macro returns non-zero if the callout is active or zero otherwise. 165