[src/netbsd-1-4]: src/share/man/man9 Pull up revision 1.1 (new, requested by ...

[he <he%NetBSD.org@localhost>]

details:   https://anonhg.NetBSD.org/src/rev/6a3aa8567a29
branches:  netbsd-1-4
changeset: 470381:6a3aa8567a29
user:      he <he%NetBSD.org@localhost>
date:      Fri Feb 18 20:26:43 2000 +0000

description:
Pull up revision 1.1 (new, requested by thorpej):
  Implement ratecheck(), a function which can help kernel programmers
  implement rate-limited actions.

diffstat:

 share/man/man9/ratecheck.9 |  140 +++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 140 insertions(+), 0 deletions(-)

diffs (144 lines):

diff -r ed23fbfddb16 -r 6a3aa8567a29 share/man/man9/ratecheck.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/ratecheck.9        Fri Feb 18 20:26:43 2000 +0000
@@ -0,0 +1,140 @@
+.\"    $NetBSD: ratecheck.9,v 1.1.2.2 2000/02/18 20:26:43 he Exp $
+.\"
+.\" Copyright (c) 2000 The NetBSD Foundation, Inc.
+.\" All rights reserved.
+.\"
+.\" This code is derived from software contributed to The NetBSD Foundation
+.\" by Christopher G. Demetriou.
+.\"
+.\" Redistribution and use in source and binary forms, with or without
+.\" modification, are permitted provided that the following conditions
+.\" are met:
+.\" 1. Redistributions of source code must retain the above copyright
+.\"    notice, this list of conditions and the following disclaimer.
+.\" 2. Redistributions in binary form must reproduce the above copyright
+.\"    notice, this list of conditions and the following disclaimer in the
+.\"    documentation and/or other materials provided with the distribution.
+.\" 3. All advertising materials mentioning features or use of this software
+.\"    must display the following acknowledgement:
+.\"        This product includes software developed by the NetBSD
+.\"        Foundation, Inc. and its contributors.
+.\" 4. Neither the name of The NetBSD Foundation nor the names of its
+.\"    contributors may be used to endorse or promote products derived
+.\"    from this software without specific prior written permission.
+.\"
+.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
+.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
+.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
+.\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 
+.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+.\" POSSIBILITY OF SUCH DAMAGE.
+.\"
+.Dd February 2, 2000
+.Dt RATECHECK 9
+.Os
+.Sh NAME
+.Nm ratecheck
+.Nd function to help implement rate-limited actions
+.Sh SYNOPSIS
+.Fd #include <sys/time.h>
+.Ft int
+.Fn ratecheck "struct timeval *lasttime" "const struct timeval *mininterval"
+.Sh DESCRIPTION
+The
+.Fn ratecheck
+function provides a simple time interval check which can be used
+when implementing time-based rate-limited actions.
+If the difference between the current monotonically-increasing
+system time
+.Pq Va mono_time
+and
+.Fa lasttime
+is less than the value given by the
+.Fa mininterval
+argument, zero is returned.  Otherwise,
+.Fa lasttime
+is set to the current time and a non-zero value is returned.
+.Pp
+The motivation for implementing
+.Fn ratecheck
+was to provide a mechanism that could be used to add rate limiting to
+diagnostic message output.  If printed too often, diagnostic messages can
+keep the system from doing useful work.  If the repeated messages can
+be caused by deliberate user action or network events, they can be
+exploited to cause denial of system service.
+.Pp
+Note that using a very short time interval (less than a second)
+for
+.Fa mininterval
+defeats the purpose of this function.  (It doesn't
+take much to flood a 9600 baud serial console with output, for instance.)
+.Sh EXAMPLES
+Here is a simple example of use of the
+.Fn ratecheck
+function:
+.Bd -literal
+/*
+ * The following variables could be global, in a device softc, etc.,
+ * depending on the exact usage.
+ */
+struct timeval drv_lasterr1time;   /* time of last err1 message */
+long drv_err1count;                /* # of err1 errs since last msg */
+struct timeval drv_lasterr2time;   /* time of last err2 message */
+long drv_err2count;                /* # of err2 errs since last msg */
+
+/*
+ * the following variable will often be global or shared by all
+ * instances of a driver.  It should be initalized, so it can be
+ * patched.  Allowing it to be set via an option might be nice,
+ * but could lead to an insane proliferation of options.
+ */
+struct timeval drv_errintvl = { 5, 0 };         /* 5 seconds */
+
+/* error handling/reporting function */
+void
+drv_errhandler(int err1, int err2)
+{
+
+       /*
+        * Note that you should NOT use the same last-event
+        * time variable for dissimilar messages!
+        */
+       if (err1) {
+               /* handle err1 condition */
+               ...
+
+               drv_err1count++;
+               if (ratecheck(&drv_lasterr1notice,
+                   &drv_errinterval)) {
+                       printf("drv: %ld err1 errors occurred", 
+                           drv_err1count);
+                       drv_err1count = 0;
+               }
+       }
+       if (err2) {
+               /* handle err2 condition */
+               ...
+
+               drv_err2count++;
+               if (ratecheck(&drv_lasterr2notice,
+                   &drv_errinterval)) {
+                       printf("drv: %ld err2 errors occurred", 
+                           drv_err2count);
+                       drv_err2count = 0;
+               }
+       }
+}
+.Sh SEE ALSO
+.Xr log 9 ,
+.Xr printf 9 ,
+.Xr time 9
+.Sh HISTORY
+The
+.Fn ratecheck
+function appeared in
+.Nx 1.5 .