+++ /dev/null
-=head1 NAME
-
-his - routines for managing INN history
-
-=head1 SYNOPSIS
-
-B<#include E<lt>inn/history.hE<gt>>
-
-B<struct history;>
-
-B<struct histstats {>
-B< int hitpos;>
-B< int hitneg;>
-B< int misses;>
-B< int dne;>
-B<};>
-
-B<#define HIS_RDONLY ...>
-B<#define HIS_RDWR ...>
-B<#define HIS_CREAT ...>
-B<#define HIS_ONDISK ...>
-B<#define HIS_INCORE ...>
-B<#define HIS_MMAP ...>
-
-B<enum {>
-B< HISCTLG_PATH,>
-B< HISCTLS_PATH,>
-B< HISCTLS_SYNCCOUNT,>
-B< HISCTLS_NPAIRS,>
-B< HISCTLS_IGNOREOLD,>
-B< HISCTLS_STATINTERVAL>
-B<};>
-
-B<struct history *HISopen(const char *>I<path>B<, const char *>I<method>B<, int >I<flags>B<);>
-
-B<bool HISclose(struct history *>I<history>B<);>
-
-B<bool HISsync(struct history *>I<history>B<);>
-
-B<void HISsetcache(struct history *>I<history>B<, size_t >I<size>B<);>
-
-B<bool HISlookup(struct history *>I<history>B<, const char *>I<key>B<, time_t *>I<arrived>B<, time_t *>I<posted>B<, time_t *>I<expires>B<, TOKEN *>I<token>B<);>
-
-B<bool HIScheck(struct history *>I<history>B<, const char *>I<key>B<);>
-
-B<bool HISwrite(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<, time_t >I<posted>B<, time_t >I<expires>B<, const TOKEN *>I<token>B<);>
-
-B<bool HISremember(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<);>
-
-B<bool HISreplace(struct history *>I<history>B<, const char *>I<key>B<, time_t >I<arrived>B<, time_t >I<posted>B<, time_t >I<expires>B<, const TOKEN *>I<token>B<);>
-
-B<bool HISexpire(struct history *>I<history>B<, const char *>I<path>B<, const char *>I<reason>B<, bool >I<writing>B<, void *>I<cookie>B<, time_t >I<threshold>B<, bool (*>I<exists>B<)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));>
-
-B<bool HISwalk(struct history *>I<history>B<, const char *>I<reason>B<, void *>I<cookie>B<, bool (*>I<callback>B<)(void *cookie, time_t arrived, time_t posted, time_t expires, const TOKEN *token));>
-
-B<struct histstats HISstats(struct history *>I<history>B<);>
-
-B<const char *HISerror(struct history *>I<history>B<);>
-
-B<bool HISctl(struct history *>I<history>B<, int >I<request>B<, void *>I<val>B<);>
-
-=head1 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 B<HISopen> function opens the history file designated by I<path>
-using the mode I<flags> using the specified I<method>. I<flags> may be
-B<HIS_RDONLY> to indicate that read-only access to the history
-database is desired, or B<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 B<NULL> on failure.
-
-B<HIS_ONDISK>, B<HIS_INCORE> and B<HIS_MMAP> may be logically ORed
-into I<flags> to provide a hint to the underlying history manager as
-to how it should handle its data files; B<HIS_ONDISK> indicates that
-the caller would like as much of the data to be kept on disk (and out
-of memory), B<HIS_INCORE> indicates that the data files should be kept
-in main memory where possible and B<HIS_MMAP> that the files should be
-mmap()ed into the processes address space. B<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
-B<HISsync>() to sync the data files to disk.
-
-The B<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 B<HISopen> with I<path> set to B<NULL>, any options set
-using B<HISctl>, then the database opened by calling B<HISctl> with
-B<HISCTLS_PATH>.
-
-The B<HISclose> function closes the handle I<history> and deallocates
-any resources associated with it. It returns B<false> on failure or
-B<true> on success.
-
-The B<HISsync> function synchronises any outstanding transactions
-associated with I<history> to disk.
-
-B<HISsetcache> associates a cache used for speeding up HIScheck with
-I<history>. The cache will occupy approximately I<size> bytes.
-
-B<HISlookup> retrieves a token from I<history> based on the passed
-I<key> (normally the Message-ID). If no entry with an associated token
-can be found, B<HISlookup> will return B<false>. If a token is found
-I<arrived>, I<expires>, and I<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 I<token> being set to the
-retrieved token and a function return value of B<true>. Any of
-arrived, expires, posted, or token may be B<NULL> in which case that
-component is not returned to the caller, without affecting the return
-value.
-
-B<HIScheck> checks the database I<history> for I<key> (normally the
-Message-ID); if I<key> has previously been set via B<HISwrite>,
-B<HIScheck> returns B<true>, else B<false>.
-
-B<HISwrite> writes a new entry to the database I<history> associated
-with I<key>. I<arrived>, I<posted>, and I<expired> specify the arrival,
-posting, and expiry time respectively; I<posted> and I<expired> may be
-specifed as <= 0 in which case that component shall be treated as
-absent in the database. I<token> is associated with the specified
-I<key>. B<HISwrite> returns B<true> on success, or B<false> on
-failure. The behaviour when I<key> is not unique with respect to the
-existing entries in I<history> is unspecified.
-
-B<HISremember> writes a new entry to the database I<history>
-associated with I<key>, merely remembering that this I<key> has been
-seen, together with its arrival time I<arrived>. B<HISremember>
-returns B<true> on success, or B<false> on failure. The behaviour when
-I<key> is not unique with respect to the existing entries in
-I<history> is unspecified.
-
-B<HISreplace> replaces an existing entry in the database I<history>,
-associated with I<key>. I<arrived>, I<posted>, I<expired> specify the
-arrival, posting and expiry time respectively; I<posted> and
-I<expired> may be specifed as <= 0 in which case that component shall
-be treated as absent in the database. I<token> is associated with the
-specified I<key>; if B<NULL> then the history database merely
-remembers that this I<key> has been seen, together with its arrival
-time. B<HISreplace> returns B<true> on success, or B<false> on
-failure.
-
-B<HISexpire> expires the history database associated with I<history>,
-creating a new, replacement, database in the same location if I<path>
-is B<NULL>, or in I<path> if not B<NULL>; if I<path> is not B<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 I<writing> flag
-is normally passed as B<true>, if you wish to inhibit writing of the
-new database (and so merely see the callbacks), I<writing> may be set
-B<false>.
-
-If the underlying history mechanism needs to pause the server, the
-I<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 B<HISexpire>; if the caller wishes to inhibit pausing of
-the server, passing B<NULL> will achieve this. If I<reason> is not
-B<NULL>, then on successful return from B<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 I<exists>.
-
-If I<exists>() returns B<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 I<threshold> constraint. If I<exists>() returns B<true> the
-entry is kept as-is in the newly expired history database.
-
-The I<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
-B<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 I<threshold>
-with no token associated with them are deleted from the database.
-
-The parameter I<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.
-
-B<HISwalk> provides an iteration function for the specified I<history>
-database. For every entry in the history database, I<callback> is
-invoked, passing the I<cookie>, arrival, posting, and expiry times, in
-addition to the token associated with the entry. If the I<callback>()
-returns B<false> the iteration is aborted and B<HISwalk> returns
-B<false> to the caller.
-
-To process the entire database in the presence of a running server,
-I<reason> may be passed; if this argument is not B<NULL>, it is used
-as an an argument to the `ctlinnd (reserve|pause|go)' commands. If
-I<reason> is B<NULL> and the server is running, the behaviour of
-B<HISwalk> is undefined.
-
-If the callback function attempts to access the underlying database
-during the callback, the behaviour is unspecified.
-
-B<HISstats> returns statistics on the history cache mechanism; given a
-handle I<history>, the return value is a I<struct histstats>
-detailing:
-
-=over 4
-
-=item C<hitpos>
-
-The number of times an item was found directly in the cache and known
-to exist in the underlying history manager.
-
-=item C<hitneg>
-
-The number of times an item was found directly in the cache and known
-not to exist in the underlying history manager.
-
-=item C<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.
-
-=item C<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.
-
-=back
-
-Note that the history cache is only checked by B<HIScheck> and only
-affected by B<HIScheck>, B<HISwrite>, B<HISremember> and
-B<HISreplace>. Following a call to B<HISstats> the history statistics
-associated with I<history> are cleared.
-
-B<HISerror> returns a string describing the most recent error
-associated with I<history>; the format and content of these strings is
-history manager dependent. Note that on setting an error, the history
-API will call the B<warn> function from libinn(3).
-
-B<HISctl> provides a control interface to the underlying history
-manager. The I<request> argument determines the type of the request
-and the meaning of the I<val> argument. The values for I<request> are:
-
-=over 4
-
-=item C<HISCTLG_PATH> (const char **)
-
-Get the base file path which the history handle represents. I<val>
-should be a pointer to a location of type B<const char *>. The
-result must not later be passed to free(3).
-
-
-=item C<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
-B<HISopen(NULL, ...)>. I<val> should be a value of type B<const char
-*> and will be copied before being stored internally.
-
-=item C<HISCTLS_SYNCCOUNT> (size_t *)
-
-Set an upper bound on how many history operations may be pending in
-core before being synced to permanent storage; B<0> indicates
-unlimited. I<val> should be a pointer to a value of type B<size_t> and
-will not be modified by the call.
-
-=item C<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; B<0>
-indicates that an automatic or default sizing should be made. I<val>
-should be a pointer to a value of type B<size_t> and will not be
-modified by the call.
-
-=item C<HISCTLS_IGNOREOLD> (bool *)
-
-Instruct the underlying history manager to ignore existing database
-when creating new ones; typically this option may be set to B<true> if
-the administrator believes that the existing history database is
-corrupt and that ignoring it may help. I<val> should be a pointer to a
-value of type B<bool> and will not be modified by the call.
-
-=item C<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. I<val> should be a pointer to a value of
-type B<time_t> and will not be modified by the call.
-
-=head1 HISTORY
-
-Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
-
-$Id: libinnhist.pod 5909 2002-12-03 05:17:18Z vinocur $
~ian / innduct.git / blobdiff