Provided by: inn2-dev_2.5.3-3ubuntu1_amd64 bug

NAME

       his - routines for managing INN history

SYNOPSIS

           #include <inn/history.h>

           struct history;
           struct token;

           struct histstats {
               int hitpos;
               int hitneg;
               int misses;
               int dne;
           };

           #define HIS_RDONLY ...
           #define HIS_RDWR ...
           #define HIS_CREAT ...
           #define HIS_ONDISK ...
           #define HIS_INCORE ...
           #define HIS_MMAP ...

           enum {
               HISCTLG_PATH,
               HISCTLS_PATH,
               HISCTLS_SYNCCOUNT,
               HISCTLS_NPAIRS,
               HISCTLS_IGNOREOLD,
               HISCTLS_STATINTERVAL
           };

           struct history *HISopen(const char *path, const char *method, int flags);

           bool HISclose(struct history *history);

           bool HISsync(struct history *history);

           void HISsetcache(struct history *history, size_t size);

           bool HISlookup(struct history *history, const char *key, time_t *arrived, time_t *posted, time_t *expires, TOKEN *token);

           bool HIScheck(struct history *history, const char *key);

           bool HISwrite(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);

           bool HISremember(struct history *history, const char *key, time_t arrived, time_t posted);

           bool HISreplace(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);

           bool HISexpire(struct history *history, const char *path, const char *reason, bool writing, void *cookie, time_t threshold, bool (*exists)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));

           bool HISwalk(struct history *history, const char *reason, void *cookie, bool (*callback)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));

           struct histstats HISstats(struct history *history);

           const char *HISerror(struct history *history);

           bool HISctl(struct history *history, int request, void *val);

DESCRIPTION

       These functions provide access to the INN history database.  They maintain key/value pairs
       in an opaque database whilst providing for expiry of outdated information.

       The history structure is an opaque handle returned from HISopen.

       The HISopen function opens the history file designated by path using the mode flags using
       the specified method. flags may be HIS_RDONLY to indicate that read-only access to the
       history database is desired, or HIS_RDWR for read/write access. History methods are
       defined at build time; the history method currently available is "hisv6". On success a
       newly initialised history handle is returned, or NULL on failure.

       HIS_ONDISK, HIS_INCORE and HIS_MMAP may be logically ORed into flags to provide a hint to
       the underlying history manager as to how it should handle its data files; HIS_ONDISK
       indicates that the caller would like as much of the data to be kept on disk (and out of
       memory), HIS_INCORE indicates that the data files should be kept in main memory where
       possible and HIS_MMAP that the files should be mmap()ed into the processes address space.
       HIS_INCORE is typically used where a mass rebuild of the history database is being
       performed; the underlying history manager may assume that the caller will call HISsync()
       to sync the data files to disk.

       The HIS_CREAT flag indicates that the history database should be initialised as new; if
       any options which affect creation of the database need to be set an anonymous history
       handle should be created by calling HISopen with path set to NULL, any options set using
       HISctl, then the database opened by calling HISctl with HISCTLS_PATH.

       The HISclose function closes the handle history and deallocates any resources associated
       with it. It returns false on failure or true on success.

       The HISsync function synchronises any outstanding transactions associated with history to
       disk.

       HISsetcache associates a cache used for speeding up HIScheck with history. The cache will
       occupy approximately size bytes.

       HISlookup retrieves a token from history based on the passed key (normally the Message-
       ID). If no entry with an associated token can be found, HISlookup will return false. If a
       token is found arrived, expires, and posted are filled in with the message arrival,
       expiry, and posting times respectively (or zero, if the time component is not available),
       in addition to token being set to the retrieved token and a function return value of true.
       Any of arrived, expires, posted, or token may be NULL in which case that component is not
       returned to the caller, without affecting the return value.

       HIScheck checks the database history for key (normally the Message-ID); if key has
       previously been set via HISwrite, HIScheck returns true, else false.

       HISwrite writes a new entry to the database history associated with key. arrived, posted,
       and expired specify the arrival, posting, and expiry time respectively; posted and expired
       may be specifed as <= 0 in which case that component shall be treated as absent in the
       database. token is associated with the specified key. HISwrite returns true on success, or
       false on failure. The behaviour when key is not unique with respect to the existing
       entries in history is unspecified.

       HISremember writes a new entry to the database history associated with key, merely
       remembering that this key has been seen, together with its arrival time arrived and also
       its posting time posted, if known.  (Otherwise, its posting time may be specified as <= 0
       in case it is absent.)  HISremember returns true on success, or false on failure.  The
       behaviour when key is not unique with respect to the existing entries in history is
       unspecified.

       HISreplace replaces an existing entry in the database history, associated with key.
       arrived, posted, expired specify the arrival, posting and expiry time respectively; posted
       and expired may be specifed as <= 0 in which case that component shall be treated as
       absent in the database. token is associated with the specified key; if NULL then the
       history database merely remembers that this key has been seen, together with its arrival
       time. HISreplace returns true on success, or false on failure.

       HISexpire expires the history database associated with history, creating a new,
       replacement, database in the same location if path is NULL, or in path if not NULL; if
       path is not NULL then the replacement of the old history database with the new one is
       assumed to be performed out of band by the caller. The writing flag is normally passed as
       true, if you wish to inhibit writing of the new database (and so merely see the
       callbacks), writing may be set false.

       If the underlying history mechanism needs to pause the server, the reason string is used
       as the argument to the `ctlinnd pause' command, and as such the server should be reserved
       by the caller prior to calling HISexpire; if the caller wishes to inhibit pausing of the
       server, passing NULL will achieve this. If reason is not NULL, then on successful return
       from HISexpire the server will be left paused and the caller should unpause it.

       The history database is scanned and entries with an associated storage token are passed to
       the discrimination function exists.

       If exists() returns false it indicates that stored entity associated with token is no
       longer available (or no longer required), and therefore the associated history entry may
       be expired once it meets the threshold constraint. If exists() returns true the entry is
       kept as-is in the newly expired history database.

       The exists function is passed the arrival, posting and expiry times, in addition to the
       token associated with the entry. Note that posting and/or expiry may be zero, but that the
       token will never be NULL (such entries are handled solely via the threshold mechanism).
       The storage token passed to the discrimination function may be updated if required (for
       example, as might be needed by a hierachical storage management implementation).

       Entries in the database with a posting time less than threshold with no token associated
       with them are deleted from the database.  In case the posting time is unknown, the arrival
       time is used instead.

       The parameter cookie is passed to the discrimination function, and may be used for any
       purpose required by the caller.

       If the discrimination function attempts to access the underlying database (for read or
       write) during the callback, the behaviour is unspecified.

       HISwalk provides an iteration function for the specified history database. For every entry
       in the history database, callback is invoked, passing the cookie, arrival, posting, and
       expiry times, in addition to the token associated with the entry. If the callback()
       returns false the iteration is aborted and HISwalk returns false to the caller.

       To process the entire database in the presence of a running server, reason may be passed;
       if this argument is not NULL, it is used as an an argument to the `ctlinnd
       (reserve|pause|go)' commands. If reason is NULL and the server is running, the behaviour
       of HISwalk is undefined.

       If the callback function attempts to access the underlying database during the callback,
       the behaviour is unspecified.

       HISstats returns statistics on the history cache mechanism; given a handle history, the
       return value is a struct histstats detailing:

       "hitpos"
           The number of times an item was found directly in the cache and known to exist in the
           underlying history manager.

       "hitneg"
           The number of times an item was found directly in the cache and known not to exist in
           the underlying history manager.

       "misses"
           The number of times an item was not found directly in the cache, but on retrieval from
           the underlying history manager was found to exist.

       "dne"
           The number of times an item was not found directly in the cache, but on retrieval from
           the underlying history manager was found not to exist.

       Note that the history cache is only checked by HIScheck and only affected by HIScheck,
       HISwrite, HISremember and HISreplace. Following a call to HISstats the history statistics
       associated with history are cleared.

       HISerror returns a string describing the most recent error associated with history; the
       format and content of these strings is history manager dependent. Note that on setting an
       error, the history API will call the warn function from libinn(3).

       HISctl provides a control interface to the underlying history manager. The request
       argument determines the type of the request and the meaning of the val argument. The
       values for request are:

       "HISCTLG_PATH" (const char **)
           Get the base file path which the history handle represents. val should be a pointer to
           a location of type const char *.  The result must not later be passed to free(3).

       "HISCTLS_PATH" (const char *)
           Set the base file path which this history handle should use; typically this is used
           after an anonymous handle has been created using HISopen(NULL, ...). val should be a
           value of type const char * and will be copied before being stored internally.

       "HISCTLS_SYNCCOUNT" (size_t *)
           Set an upper bound on how many history operations may be pending in core before being
           synced to permanent storage; 0 indicates unlimited. val should be a pointer to a value
           of type size_t and will not be modified by the call.

       "HISCTLS_NPAIRS" (size_t *)
           Set a hint to the to the underlying history manager as to how many entries there are
           expected to be in the history database; 0 indicates that an automatic or default
           sizing should be made. val should be a pointer to a value of type size_t and will not
           be modified by the call.

       "HISCTLS_IGNOREOLD" (bool *)
           Instruct the underlying history manager to ignore existing database when creating new
           ones; typically this option may be set to true if the administrator believes that the
           existing history database is corrupt and that ignoring it may help. val should be a
           pointer to a value of type bool and will not be modified by the call.

       "HISCTLS_STATINTERVAL" (time_t *)
           For the history v6 and tagged hash managers, set the interval, in seconds, between
           stat(2)s of the history files checking for replaced files (as happens during expire);
           this option is typically used by nnrpd(8) like applications. val should be a pointer
           to a value of type time_t and will not be modified by the call.

HISTORY

       Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.

       $Id: libinnhist.pod 9074 2010-05-31 19:01:32Z iulius $