1.\" $NetBSD: rt_timer.9,v 1.9 2002/10/14 13:43:32 wiz Exp $ 2.\" 3.\" Copyright (c) 1998 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Kevin M. Lahey of the Numerical Aerospace Simulation Facility, 8.\" NASA Ames Research Center. 9.\" 10.\" Redistribution and use in source and binary forms, with or without 11.\" modification, are permitted provided that the following conditions 12.\" are met: 13.\" 1. Redistributions of source code must retain the above copyright 14.\" notice, this list of conditions and the following disclaimer. 15.\" 2. Redistributions in binary form must reproduce the above copyright 16.\" notice, this list of conditions and the following disclaimer in the 17.\" documentation and/or other materials provided with the distribution. 18.\" 3. All advertising materials mentioning features or use of this software 19.\" must display the following acknowledgment: 20.\" This product includes software developed by the NetBSD 21.\" Foundation, Inc. and its contributors. 22.\" 4. Neither the name of The NetBSD Foundation nor the names of its 23.\" contributors may be used to endorse or promote products derived 24.\" from this software without specific prior written permission. 25.\" 26.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 27.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 28.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 29.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 30.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 31.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 32.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 33.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 34.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 35.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 36.\" POSSIBILITY OF SUCH DAMAGE. 37.\" 38.Dd April 23, 1998 39.Dt RT_TIMER 9 40.Os 41.Sh NAME 42.Nm rt_timer , 43.Nm rt_timer_add , 44.Nm rt_timer_queue_create , 45.Nm rt_timer_queue_change , 46.Nm rt_timer_queue_destroy , 47.Nm rt_timer_remove_all 48.Nd route callout functions 49.Sh SYNOPSIS 50.Fd #include \*[Lt]net/route.h\*[Gt] 51.Ft "struct rttimer_queue *" 52.Fn rt_timer_queue_create "time_t timeout" 53.Ft void 54.Fn rt_timer_queue_change "struct rttimer_queue *q" "time_t timeout" 55.Ft void 56.Fn rt_timer_queue_destroy "struct rttimer_queue *q" "int destroy" 57.Ft int 58.Fn rt_timer_add "struct rtentry *rt" \ 59"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" 60.Ft void 61.Fn rt_timer_remove_all "struct rtentry *rt" 62.Sh DESCRIPTION 63The 64.Nm 65functions provide a generic route callout functionality. 66They allow a function to be called for a route at any time. 67This was originally intended to be used to remove routes added 68by path MTU discovery code. 69.Pp 70For maximum efficiency, a separate queue should be defined for each 71timeout period. 72For example, one queue should be created for the 10 minute path MTU 73discovery timeouts, another for 20 minute ARP timeouts after 20 74minutes, and so on. 75This permits extremely fast queue manipulations so that the timeout 76functions remain scalable, even in the face of thousands of route 77manipulations per minute. 78.Pp 79It is possible to create only a single timeout queue for all possible 80timeout values, but doing so is not scalable as queue manipulations 81become quite expensive if the timeout deltas are not roughly constant. 82.Pp 83The 84.Nm 85interface provides the following functions: 86.Bl -tag -width compact 87.It Fn rt_timer_queue_create "time_t timeout" 88This function creates a new timer queue with the specified timeout period 89.Fa timeout , 90expressed in seconds. 91.It Fn rt_timer_queue_change "rttimer_queue *q" "time_t timeout" 92This function modifies the timeout period for a timer queue. 93Any value, including 0, is valid. 94The next time the timer queue's timeout expires (based on the previous 95timeout value), all entries which are valid to execute based on the new 96timeout will be executed, and the new timeout period scheduled. 97.It Fn rt_timer_queue_destroy "rttimer_queue *q" "int destroy" 98This function destroys a timeout queue. 99All entries are removed, and if the 100.Fa destroy 101argument is non-zero, the timeout action is performed for each entry. 102.It Fn rt_timer_add "struct rtentry *rt" \ 103"void(*f)(struct rtentry *, struct rttimer *)" "struct rttimer_queue *q" 104This function adds an entry to a timeout queue. 105The function 106.Fa f 107will be called after the timeout period for queue 108.Fa q 109has elapsed. 110If 111.Fa f 112is NULL 113the route will be deleted when the timeout expires. 114.It Fn rt_timer_remove_all "struct rtentry *rt" 115This function removes all references to the given route from the 116.Nm 117subsystem. 118This is used when a route is deleted to ensure that no dangling 119references remain. 120.El 121.Sh SEE ALSO 122.Xr netstat 1 , 123.Xr arp 9 124.Sh AUTHORS 125This interface is roughly based on (but, alas, not compatible with) one 126designed by David Borman of BSDI. 127This implementation is by Kevin Lahey of the Numerical Aerospace 128Simulation Facility, NASA Ames Research Center. 129.Sh CODE REFERENCES 130The 131.Nm 132interface is implemented in 133.Pa sys/net/route.h 134and 135.Pa sys/net/route.c . 136.Sh HISTORY 137The 138.Nm 139interface appeared in 140.Nx 1.4 . 141