1.\" $NetBSD: ratecheck.9,v 1.7 2002/02/13 08:18:50 ross 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. Otherwise, 60.Fa lasttime 61is set to the current time and a non-zero value is returned. 62.Pp 63The motivation for implementing 64.Fn ratecheck 65was to provide a mechanism that could be used to add rate limiting to 66diagnostic message output. If printed too often, diagnostic messages can 67keep the system from doing useful work. If the repeated messages can 68be caused by deliberate user action or network events, they can be 69exploited to cause denial of system service. 70.Pp 71Note that using a very short time interval (less than a second) 72for 73.Fa mininterval 74defeats the purpose of this function. (It doesn't 75take much to flood a 9600 baud serial console with output, for instance.) 76.Sh EXAMPLES 77Here is a simple example of use of the 78.Fn ratecheck 79function: 80.Bd -literal 81/* 82 * The following variables could be global, in a device softc, etc., 83 * depending on the exact usage. 84 */ 85struct timeval drv_lasterr1time; /* time of last err1 message */ 86long drv_err1count; /* # of err1 errs since last msg */ 87struct timeval drv_lasterr2time; /* time of last err2 message */ 88long drv_err2count; /* # of err2 errs since last msg */ 89 90/* 91 * the following variable will often be global or shared by all 92 * instances of a driver. It should be initialized, so it can be 93 * patched. Allowing it to be set via an option might be nice, 94 * but could lead to an insane proliferation of options. 95 */ 96struct timeval drv_errintvl = { 5, 0 }; /* 5 seconds */ 97 98/* error handling/reporting function */ 99void 100drv_errhandler(int err1, int err2) 101{ 102 103 /* 104 * Note that you should NOT use the same last-event 105 * time variable for dissimilar messages! 106 */ 107 if (err1) { 108 /* handle err1 condition */ 109 ... 110 111 drv_err1count++; 112 if (ratecheck(\*[Am]drv_lasterr1notice, 113 \*[Am]drv_errinterval)) { 114 printf("drv: %ld err1 errors occurred", 115 drv_err1count); 116 drv_err1count = 0; 117 } 118 } 119 if (err2) { 120 /* handle err2 condition */ 121 ... 122 123 drv_err2count++; 124 if (ratecheck(\*[Am]drv_lasterr2notice, 125 \*[Am]drv_errinterval)) { 126 printf("drv: %ld err2 errors occurred", 127 drv_err2count); 128 drv_err2count = 0; 129 } 130 } 131} 132.Ed 133.Sh SEE ALSO 134.Xr log 9 , 135.Xr ppsratecheck 9 , 136.Xr printf 9 , 137.Xr time 9 138.Sh HISTORY 139The 140.Fn ratecheck 141function appeared in 142.Nx 1.5 . 143.Sh BUGS 144.Fn ratecheck 145may not work as expected, if 146.Fa mininterval 147is less than the hardware clock interrupt interval 148.Pq Li 1/hz . 149