libinnhist man page on SuSE

Man page or keyword search:  
man Server   14857 pages
apropos Keyword Search (all sections)
Output format
SuSE logo
[printable version]

libinnhist(3)		  InterNetNews Documentation		 libinnhist(3)

NAME
       his - routines for managing INN history

SYNOPSIS
       #include <inn/history.h>

       struct history;

       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);

       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 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 pos‐
       sible 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 ini‐
       tialised 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 associ‐
       ated with history to disk.

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

       HISlookup retrieves a token from history based on the passed key (nor‐
       mally 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. 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, associ‐
       ated 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 data‐
       base. token is associated with the specified key; if NULL then the his‐
       tory 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, creat‐
       ing 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 rea‐
       son 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, pass‐
       ing 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 there‐
       fore 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 updated if required
       (for example, as might be needed by a hierachical storage management
       implementation).

       Entries in the database with an arrival time less than threshold with
       no token associated with them are deleted from the database.

       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 data‐
       base (for read or write) during the callback, the behaviour is unspeci‐
       fied.

       HISwalk provides an iteration function for the specified history data‐
       base. 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 man‐
       ager 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; typi‐
	   cally 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 unlim‐
	   ited. 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 indi‐
	   cates 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 modi‐
	   fied 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.3,v 1.7 2002/12/03 05:31:10 vinocur Exp $

INN 2.4.0			  2002-12-03			 libinnhist(3)
[top]

List of man pages available for SuSE

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net