1.\" $NetBSD: ratecheck.9,v 1.8 2002/10/14 13:43:31 wiz Exp $ 2.\" 3.\" Copyright (c) 2000 The NetBSD Foundation, Inc. 4.\" All rights reserved. 5.\" 6.\" This code is derived from software contributed to The NetBSD Foundation 7.\" by Christopher G. Demetriou. 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 FOUNDATION OR CONTRIBUTORS 29.\" BE 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.Dd February 2, 2000 38.Dt RATECHECK 9 39.Os 40.Sh NAME 41.Nm ratecheck 42.Nd function to help implement rate-limited actions 43.Sh SYNOPSIS 44.Fd #include \*[Lt]sys/time.h\*[Gt] 45.Ft int 46.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval" 47.Sh DESCRIPTION 48The 49.Fn ratecheck 50function provides a simple time interval check which can be used 51when implementing time-based rate-limited actions. 52If the difference between the current monotonically-increasing 53system time 54.Pq Va mono_time 55and 56.Fa lasttime 57is less than the value given by the 58.Fa mininterval 59argument, zero is returned. 60Otherwise, 61.Fa lasttime 62is set to the current time and a non-zero value is returned. 63.Pp 64The motivation for implementing 65.Fn ratecheck 66was to provide a mechanism that could be used to add rate limiting to 67diagnostic message output. 68If printed too often, diagnostic messages can keep the system from 69doing useful work. 70If the repeated messages can be caused by deliberate user action 71or network events, they can be exploited to cause denial of system service. 72.Pp 73Note that using a very short time interval (less than a second) 74for 75.Fa mininterval 76defeats the purpose of this function. 77(It doesn't take much to flood a 9600 baud serial console with 78output, for instance.) 79.Sh EXAMPLES 80Here is a simple example of use of the 81.Fn ratecheck 82function: 83.Bd -literal 84/* 85 * The following variables could be global, in a device softc, etc., 86 * depending on the exact usage. 87 */ 88struct timeval drv_lasterr1time; /* time of last err1 message */ 89long drv_err1count; /* # of err1 errs since last msg */ 90struct timeval drv_lasterr2time; /* time of last err2 message */ 91long drv_err2count; /* # of err2 errs since last msg */ 92 93/* 94 * The following variable will often be global or shared by all 95 * instances of a driver. It should be initialized, so it can be 96 * patched. Allowing it to be set via an option might be nice, 97 * but could lead to an insane proliferation of options. 98 */ 99struct timeval drv_errintvl = { 5, 0 }; /* 5 seconds */ 100 101/* error handling/reporting function */ 102void 103drv_errhandler(int err1, int err2) 104{ 105 106 /* 107 * Note that you should NOT use the same last-event 108 * time variable for dissimilar messages! 109 */ 110 if (err1) { 111 /* handle err1 condition */ 112 ... 113 114 drv_err1count++; 115 if (ratecheck(\*[Am]drv_lasterr1notice, 116 \*[Am]drv_errinterval)) { 117 printf("drv: %ld err1 errors occurred", 118 drv_err1count); 119 drv_err1count = 0; 120 } 121 } 122 if (err2) { 123 /* handle err2 condition */ 124 ... 125 126 drv_err2count++; 127 if (ratecheck(\*[Am]drv_lasterr2notice, 128 \*[Am]drv_errinterval)) { 129 printf("drv: %ld err2 errors occurred", 130 drv_err2count); 131 drv_err2count = 0; 132 } 133 } 134} 135.Ed 136.Sh SEE ALSO 137.Xr log 9 , 138.Xr ppsratecheck 9 , 139.Xr printf 9 , 140.Xr time 9 141.Sh HISTORY 142The 143.Fn ratecheck 144function appeared in 145.Nx 1.5 . 146.Sh BUGS 147.Fn ratecheck 148may not work as expected, if 149.Fa mininterval 150is less than the hardware clock interrupt interval 151.Pq Li 1/hz . 152