NAME    [Toc]    [Back]

     ratecheck - function to help implement rate-limited actions

SYNOPSIS    [Toc]    [Back]

     #include <sys/time.h>

     int
     ratecheck(struct timeval  *lasttime,  const  struct  timeval
*mininterval);

DESCRIPTION    [Toc]    [Back]

     The  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
     (mono_time) and lasttime is less than the value given by the
mininterval
     argument,  zero  is returned.  Otherwise, lasttime is set to
the current
     time and a non-zero value is returned.

     The motivation for implementing 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.

     Note that using a very short time interval (less than a second) for
     mininterval defeats  the  purpose  of  this  function.   (It
doesn't take much
     to  flood  a  9600  baud serial console with output, for instance.)

EXAMPLES    [Toc]    [Back]

     Here is a simple example of use of the ratecheck() function:

     /*
      *  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 initialized, 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;
                     }
             }
     }

SEE ALSO    [Toc]    [Back]

     log(9), printf(9), time(9)

HISTORY    [Toc]    [Back]

     The ratecheck() function first appeared in NetBSD 1.5.

OpenBSD     3.6                        February      2,      2000