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