1.\" $NetBSD: ratecheck.9,v 1.11 2008/04/30 13:10:58 martin 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd February 2, 2000 31.Dt RATECHECK 9 32.Os 33.Sh NAME 34.Nm ratecheck 35.Nd function to help implement rate-limited actions 36.Sh SYNOPSIS 37.In sys/time.h 38.Ft int 39.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval" 40.Sh DESCRIPTION 41The 42.Fn ratecheck 43function provides a simple time interval check which can be used 44when implementing time-based rate-limited actions. 45If the difference between the current monotonically-increasing 46system time 47.Pq Va mono_time 48and 49.Fa lasttime 50is less than the value given by the 51.Fa mininterval 52argument, zero is returned. 53Otherwise, 54.Fa lasttime 55is set to the current time and a non-zero value is returned. 56.Pp 57The motivation for implementing 58.Fn ratecheck 59was to provide a mechanism that could be used to add rate limiting to 60diagnostic message output. 61If printed too often, diagnostic messages can keep the system from 62doing useful work. 63If the repeated messages can be caused by deliberate user action 64or network events, they can be exploited to cause denial of system service. 65.Pp 66Note that using a very short time interval (less than a second) 67for 68.Fa mininterval 69defeats the purpose of this function. 70(It doesn't take much to flood a 9600 baud serial console with 71output, for instance.) 72.Sh EXAMPLES 73Here is a simple example of use of the 74.Fn ratecheck 75function: 76.Bd -literal 77/* 78 * The following variables could be global, in a device softc, etc., 79 * depending on the exact usage. 80 */ 81struct timeval drv_lasterr1time; /* time of last err1 message */ 82long drv_err1count; /* # of err1 errs since last msg */ 83struct timeval drv_lasterr2time; /* time of last err2 message */ 84long drv_err2count; /* # of err2 errs since last msg */ 85 86/* 87 * The following variable will often be global or shared by all 88 * instances of a driver. It should be initialized, so it can be 89 * patched. Allowing it to be set via an option might be nice, 90 * but could lead to an insane proliferation of options. 91 */ 92struct timeval drv_errintvl = { 5, 0 }; /* 5 seconds */ 93 94/* error handling/reporting function */ 95void 96drv_errhandler(int err1, int err2) 97{ 98 99 /* 100 * Note that you should NOT use the same last-event 101 * time variable for dissimilar messages! 102 */ 103 if (err1) { 104 /* handle err1 condition */ 105 ... 106 107 drv_err1count++; 108 if (ratecheck(\*[Am]drv_lasterr1notice, 109 \*[Am]drv_errinterval)) { 110 printf("drv: %ld err1 errors occurred", 111 drv_err1count); 112 drv_err1count = 0; 113 } 114 } 115 if (err2) { 116 /* handle err2 condition */ 117 ... 118 119 drv_err2count++; 120 if (ratecheck(\*[Am]drv_lasterr2notice, 121 \*[Am]drv_errinterval)) { 122 printf("drv: %ld err2 errors occurred", 123 drv_err2count); 124 drv_err2count = 0; 125 } 126 } 127} 128.Ed 129.Sh SEE ALSO 130.Xr log 9 , 131.Xr ppsratecheck 9 , 132.Xr printf 9 , 133.Xr time_second 9 134.Sh HISTORY 135The 136.Fn ratecheck 137function appeared in 138.Nx 1.5 . 139.Sh BUGS 140.Fn ratecheck 141may not work as expected, if 142.Fa mininterval 143is less than the hardware clock interrupt interval 144.Pq Li 1/hz . 145