share/man/man9/ratecheck.9

   1 .\" $NetBSD: ratecheck.9,v 1.10 2007/02/20 08:26:35 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 .\"
  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
  41 The
  42 .Fn ratecheck
  43 function provides a simple time interval check which can be used
  44 when implementing time-based rate-limited actions.
  45 If the difference between the current monotonically-increasing
  46 system time
  47 .Pq Va mono_time
  48 and
  49 .Fa lasttime
  50 is less than the value given by the
  51 .Fa mininterval
  52 argument, zero is returned.
  53 Otherwise,
  54 .Fa lasttime
  55 is set to the current time and a non-zero value is returned.
  56 .Pp
  57 The motivation for implementing
  58 .Fn ratecheck
  59 was to provide a mechanism that could be used to add rate limiting to
  60 diagnostic message output.
  61 If printed too often, diagnostic messages can keep the system from
  62 doing useful work.
  63 If the repeated messages can be caused by deliberate user action
  64 or network events, they can be exploited to cause denial of system service.
  65 .Pp
  66 Note that using a very short time interval (less than a second)
  67 for
  68 .Fa mininterval
  69 defeats the purpose of this function.
  70 (It doesn't take much to flood a 9600 baud serial console with
  71 output, for instance.)
  72 .Sh EXAMPLES
  73 Here is a simple example of use of the
  74 .Fn ratecheck
  75 function:
  76 .Bd -literal
  77 /*
  78  * The following variables could be global, in a device softc, etc.,
  79  * depending on the exact usage.
  80  */
  81 struct timeval drv_lasterr1time;   /* time of last err1 message */
  82 long drv_err1count;                /* # of err1 errs since last msg */
  83 struct timeval drv_lasterr2time;   /* time of last err2 message */
  84 long 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  */
  92 struct timeval drv_errintvl = { 5, 0 };         /* 5 seconds */
  93
  94 /* error handling/reporting function */
  95 void
  96 drv_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
 135 The
 136 .Fn ratecheck
 137 function appeared in
 138 .Nx 1.5 .
 139 .Sh BUGS
 140 .Fn ratecheck
 141 may not work as expected, if
 142 .Fa mininterval
 143 is less than the hardware clock interrupt interval
 144 .Pq Li 1/hz .