Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
libinnhist(3)		  InterNetNews Documentation		 libinnhist(3)

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 specified 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
       specified 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 hierarchical 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 10283 2018-05-14 12:43:05Z iulius $

INN 2.6.3			  2018-05-14			 libinnhist(3)

NAME | SYNOPSIS | DESCRIPTION | HISTORY

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=libinnhist&sektion=3&manpath=FreeBSD+13.0-RELEASE+and+Ports>

home | help