[src/trunk]: src/share/man/man9 add documentation for the ratecheck() functio...

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

details:   https://anonhg.NetBSD.org/src/rev/24d9065385b4
branches:  trunk
changeset: 481694:24d9065385b4
user:      cgd <cgd%NetBSD.org@localhost>
date:      Thu Feb 03 23:03:14 2000 +0000

description:
add documentation for the ratecheck() function, a new kernel function
(not even committed... docs before changes?!  CALL RIPLEY!!!)
which can help programmers implement rate-limited actions.

diffstat:

 share/man/man9/Makefile    |    4 +-
 share/man/man9/ratecheck.9 |  140 +++++++++++++++++++++++++++++++++++++++++++++
 2 files changed, 142 insertions(+), 2 deletions(-)

diffs (162 lines):

diff -r 605fd6379ab2 -r 24d9065385b4 share/man/man9/Makefile
--- a/share/man/man9/Makefile   Thu Feb 03 23:03:11 2000 +0000
+++ b/share/man/man9/Makefile   Thu Feb 03 23:03:14 2000 +0000
@@ -1,4 +1,4 @@
-#       $NetBSD: Makefile,v 1.56 2000/01/07 21:14:25 kleink Exp $
+#       $NetBSD: Makefile,v 1.57 2000/02/03 23:03:14 cgd Exp $
 
 #      Makefile for section 9 (kernel function and variable) manual pages.
 
@@ -7,7 +7,7 @@
        ethersubr.9 extent.9 fetch.9 fork1.9 humanize_number.9 \
        inittodr.9 intro.9 ioctl.9 kprintf.9 \
        log.9 malloc.9 mbuf.9 microtime.9 panic.9 pfil.9 physio.9 pool.9 \
-       powerhook_establish.9 psignal.9 resettodr.9 rnd.9 \
+       powerhook_establish.9 psignal.9 ratecheck.9 resettodr.9 rnd.9 \
        rt_timer.9 shutdownhook_establish.9 \
        sleep.9 spl.9 store.9 time.9 timeout.9 uiomove.9 usbdi.9 uvm.9 \
        wdc.9
diff -r 605fd6379ab2 -r 24d9065385b4 share/man/man9/ratecheck.9
--- /dev/null   Thu Jan 01 00:00:00 1970 +0000
+++ b/share/man/man9/ratecheck.9        Thu Feb 03 23:03:14 2000 +0000
@@ -0,0 +1,140 @@
+.\"    $NetBSD: ratecheck.9,v 1.1 2000/02/03 23:03:14 cgd 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 .