+++ /dev/null
-.\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32
-.\"
-.\" Standard preamble:
-.\" ========================================================================
-.de Sh \" Subsection heading
-.br
-.if t .Sp
-.ne 5
-.PP
-\fB\\$1\fR
-.PP
-..
-.de Sp \" Vertical space (when we can't use .PP)
-.if t .sp .5v
-.if n .sp
-..
-.de Vb \" Begin verbatim text
-.ft CW
-.nf
-.ne \\$1
-..
-.de Ve \" End verbatim text
-.ft R
-.fi
-..
-.\" Set up some character translations and predefined strings. \*(-- will
-.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
-.\" double quote, and \*(R" will give a right double quote. \*(C+ will
-.\" give a nicer C++. Capital omega is used to do unbreakable dashes and
-.\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff,
-.\" nothing in troff, for use with C<>.
-.tr \(*W-
-.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
-.ie n \{\
-. ds -- \(*W-
-. ds PI pi
-. if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
-. if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
-. ds L" ""
-. ds R" ""
-. ds C` ""
-. ds C' ""
-'br\}
-.el\{\
-. ds -- \|\(em\|
-. ds PI \(*p
-. ds L" ``
-. ds R" ''
-'br\}
-.\"
-.\" If the F register is turned on, we'll generate index entries on stderr for
-.\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index
-.\" entries marked with X<> in POD. Of course, you'll have to process the
-.\" output yourself in some meaningful fashion.
-.if \nF \{\
-. de IX
-. tm Index:\\$1\t\\n%\t"\\$2"
-..
-. nr % 0
-. rr F
-.\}
-.\"
-.\" For nroff, turn off justification. Always turn off hyphenation; it makes
-.\" way too many mistakes in technical documents.
-.hy 0
-.if n .na
-.\"
-.\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
-.\" Fear. Run. Save yourself. No user-serviceable parts.
-. \" fudge factors for nroff and troff
-.if n \{\
-. ds #H 0
-. ds #V .8m
-. ds #F .3m
-. ds #[ \f1
-. ds #] \fP
-.\}
-.if t \{\
-. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
-. ds #V .6m
-. ds #F 0
-. ds #[ \&
-. ds #] \&
-.\}
-. \" simple accents for nroff and troff
-.if n \{\
-. ds ' \&
-. ds ` \&
-. ds ^ \&
-. ds , \&
-. ds ~ ~
-. ds /
-.\}
-.if t \{\
-. ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
-. ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
-. ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
-. ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
-. ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
-. ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
-.\}
-. \" troff and (daisy-wheel) nroff accents
-.ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
-.ds 8 \h'\*(#H'\(*b\h'-\*(#H'
-.ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
-.ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
-.ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
-.ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
-.ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
-.ds ae a\h'-(\w'a'u*4/10)'e
-.ds Ae A\h'-(\w'A'u*4/10)'E
-. \" corrections for vroff
-.if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
-.if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
-. \" for low resolution devices (crt and lpr)
-.if \n(.H>23 .if \n(.V>19 \
-\{\
-. ds : e
-. ds 8 ss
-. ds o a
-. ds d- d\h'-1'\(ga
-. ds D- D\h'-1'\(hy
-. ds th \o'bp'
-. ds Th \o'LP'
-. ds ae ae
-. ds Ae AE
-.\}
-.rm #[ #] #H #V #F C
-.\" ========================================================================
-.\"
-.IX Title "libinnhist 3"
-.TH libinnhist 3 "2008-04-06" "INN 2.4.5" "InterNetNews Documentation"
-.SH "NAME"
-his \- routines for managing INN history
-.SH "SYNOPSIS"
-.IX Header "SYNOPSIS"
-\&\fB#include <inn/history.h>\fR
-.PP
-\&\fBstruct history;\fR
-.PP
-\&\fBstruct histstats {\fR
-\&\fB int hitpos;\fR
-\&\fB int hitneg;\fR
-\&\fB int misses;\fR
-\&\fB int dne;\fR
-\&\fB};\fR
-.PP
-\&\fB#define \s-1HIS_RDONLY\s0 ...\fR
-\&\fB#define \s-1HIS_RDWR\s0 ...\fR
-\&\fB#define \s-1HIS_CREAT\s0 ...\fR
-\&\fB#define \s-1HIS_ONDISK\s0 ...\fR
-\&\fB#define \s-1HIS_INCORE\s0 ...\fR
-\&\fB#define \s-1HIS_MMAP\s0 ...\fR
-.PP
-\&\fBenum {\fR
-\&\fB \s-1HISCTLG_PATH\s0,\fR
-\&\fB \s-1HISCTLS_PATH\s0,\fR
-\&\fB \s-1HISCTLS_SYNCCOUNT\s0,\fR
-\&\fB \s-1HISCTLS_NPAIRS\s0,\fR
-\&\fB \s-1HISCTLS_IGNOREOLD\s0,\fR
-\&\fB \s-1HISCTLS_STATINTERVAL\s0\fR
-\&\fB};\fR
-.PP
-\&\fBstruct history *HISopen(const char *\fR\fIpath\fR\fB, const char *\fR\fImethod\fR\fB, int \fR\fIflags\fR\fB);\fR
-.PP
-\&\fBbool HISclose(struct history *\fR\fIhistory\fR\fB);\fR
-.PP
-\&\fBbool HISsync(struct history *\fR\fIhistory\fR\fB);\fR
-.PP
-\&\fBvoid HISsetcache(struct history *\fR\fIhistory\fR\fB, size_t \fR\fIsize\fR\fB);\fR
-.PP
-\&\fBbool HISlookup(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIkey\fR\fB, time_t *\fR\fIarrived\fR\fB, time_t *\fR\fIposted\fR\fB, time_t *\fR\fIexpires\fR\fB, \s-1TOKEN\s0 *\fR\fItoken\fR\fB);\fR
-.PP
-\&\fBbool HIScheck(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIkey\fR\fB);\fR
-.PP
-\&\fBbool HISwrite(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIkey\fR\fB, time_t \fR\fIarrived\fR\fB, time_t \fR\fIposted\fR\fB, time_t \fR\fIexpires\fR\fB, const \s-1TOKEN\s0 *\fR\fItoken\fR\fB);\fR
-.PP
-\&\fBbool HISremember(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIkey\fR\fB, time_t \fR\fIarrived\fR\fB);\fR
-.PP
-\&\fBbool HISreplace(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIkey\fR\fB, time_t \fR\fIarrived\fR\fB, time_t \fR\fIposted\fR\fB, time_t \fR\fIexpires\fR\fB, const \s-1TOKEN\s0 *\fR\fItoken\fR\fB);\fR
-.PP
-\&\fBbool HISexpire(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIpath\fR\fB, const char *\fR\fIreason\fR\fB, bool \fR\fIwriting\fR\fB, void *\fR\fIcookie\fR\fB, time_t \fR\fIthreshold\fR\fB, bool (*\fR\fIexists\fR\fB)(void *cookie, time_t arrived, time_t posted, time_t expires, const \s-1TOKEN\s0 *token));\fR
-.PP
-\&\fBbool HISwalk(struct history *\fR\fIhistory\fR\fB, const char *\fR\fIreason\fR\fB, void *\fR\fIcookie\fR\fB, bool (*\fR\fIcallback\fR\fB)(void *cookie, time_t arrived, time_t posted, time_t expires, const \s-1TOKEN\s0 *token));\fR
-.PP
-\&\fBstruct histstats HISstats(struct history *\fR\fIhistory\fR\fB);\fR
-.PP
-\&\fBconst char *HISerror(struct history *\fR\fIhistory\fR\fB);\fR
-.PP
-\&\fBbool HISctl(struct history *\fR\fIhistory\fR\fB, int \fR\fIrequest\fR\fB, void *\fR\fIval\fR\fB);\fR
-.SH "DESCRIPTION"
-.IX Header "DESCRIPTION"
-These functions provide provide access to the \s-1INN\s0 history
-database. They maintain key/value pairs in an opaque database whilst
-providing for expiry of outdated information.
-.PP
-The history structure is an opaque handle returned from HISopen.
-.PP
-The \fBHISopen\fR function opens the history file designated by \fIpath\fR
-using the mode \fIflags\fR using the specified \fImethod\fR. \fIflags\fR may be
-\&\fB\s-1HIS_RDONLY\s0\fR to indicate that read-only access to the history
-database is desired, or \fB\s-1HIS_RDWR\s0\fR for read/write access. History
-methods are defined at build time; the history method currently
-available is \*(L"hisv6\*(R". On success a newly initialised history handle is
-returned, or \fB\s-1NULL\s0\fR on failure.
-.PP
-\&\fB\s-1HIS_ONDISK\s0\fR, \fB\s-1HIS_INCORE\s0\fR and \fB\s-1HIS_MMAP\s0\fR may be logically ORed
-into \fIflags\fR to provide a hint to the underlying history manager as
-to how it should handle its data files; \fB\s-1HIS_ONDISK\s0\fR indicates that
-the caller would like as much of the data to be kept on disk (and out
-of memory), \fB\s-1HIS_INCORE\s0\fR indicates that the data files should be kept
-in main memory where possible and \fB\s-1HIS_MMAP\s0\fR that the files should be
-\&\fImmap()\fRed into the processes address space. \fB\s-1HIS_INCORE\s0\fR 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
-\&\fBHISsync\fR() to sync the data files to disk.
-.PP
-The \fB\s-1HIS_CREAT\s0\fR 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 \fBHISopen\fR with \fIpath\fR set to \fB\s-1NULL\s0\fR, any options set
-using \fBHISctl\fR, then the database opened by calling \fBHISctl\fR with
-\&\fB\s-1HISCTLS_PATH\s0\fR.
-.PP
-The \fBHISclose\fR function closes the handle \fIhistory\fR and deallocates
-any resources associated with it. It returns \fBfalse\fR on failure or
-\&\fBtrue\fR on success.
-.PP
-The \fBHISsync\fR function synchronises any outstanding transactions
-associated with \fIhistory\fR to disk.
-.PP
-\&\fBHISsetcache\fR associates a cache used for speeding up HIScheck with
-\&\fIhistory\fR. The cache will occupy approximately \fIsize\fR bytes.
-.PP
-\&\fBHISlookup\fR retrieves a token from \fIhistory\fR based on the passed
-\&\fIkey\fR (normally the Message\-ID). If no entry with an associated token
-can be found, \fBHISlookup\fR will return \fBfalse\fR. If a token is found
-\&\fIarrived\fR, \fIexpires\fR, and \fIposted\fR are filled in with the message
-arrival, expiry, and posting times respectively (or zero, if the time
-component is not available), in addition to \fItoken\fR being set to the
-retrieved token and a function return value of \fBtrue\fR. Any of
-arrived, expires, posted, or token may be \fB\s-1NULL\s0\fR in which case that
-component is not returned to the caller, without affecting the return
-value.
-.PP
-\&\fBHIScheck\fR checks the database \fIhistory\fR for \fIkey\fR (normally the
-Message\-ID); if \fIkey\fR has previously been set via \fBHISwrite\fR,
-\&\fBHIScheck\fR returns \fBtrue\fR, else \fBfalse\fR.
-.PP
-\&\fBHISwrite\fR writes a new entry to the database \fIhistory\fR associated
-with \fIkey\fR. \fIarrived\fR, \fIposted\fR, and \fIexpired\fR specify the arrival,
-posting, and expiry time respectively; \fIposted\fR and \fIexpired\fR may be
-specifed as <= 0 in which case that component shall be treated as
-absent in the database. \fItoken\fR is associated with the specified
-\&\fIkey\fR. \fBHISwrite\fR returns \fBtrue\fR on success, or \fBfalse\fR on
-failure. The behaviour when \fIkey\fR is not unique with respect to the
-existing entries in \fIhistory\fR is unspecified.
-.PP
-\&\fBHISremember\fR writes a new entry to the database \fIhistory\fR
-associated with \fIkey\fR, merely remembering that this \fIkey\fR has been
-seen, together with its arrival time \fIarrived\fR. \fBHISremember\fR
-returns \fBtrue\fR on success, or \fBfalse\fR on failure. The behaviour when
-\&\fIkey\fR is not unique with respect to the existing entries in
-\&\fIhistory\fR is unspecified.
-.PP
-\&\fBHISreplace\fR replaces an existing entry in the database \fIhistory\fR,
-associated with \fIkey\fR. \fIarrived\fR, \fIposted\fR, \fIexpired\fR specify the
-arrival, posting and expiry time respectively; \fIposted\fR and
-\&\fIexpired\fR may be specifed as <= 0 in which case that component shall
-be treated as absent in the database. \fItoken\fR is associated with the
-specified \fIkey\fR; if \fB\s-1NULL\s0\fR then the history database merely
-remembers that this \fIkey\fR has been seen, together with its arrival
-time. \fBHISreplace\fR returns \fBtrue\fR on success, or \fBfalse\fR on
-failure.
-.PP
-\&\fBHISexpire\fR expires the history database associated with \fIhistory\fR,
-creating a new, replacement, database in the same location if \fIpath\fR
-is \fB\s-1NULL\s0\fR, or in \fIpath\fR if not \fB\s-1NULL\s0\fR; if \fIpath\fR is not \fB\s-1NULL\s0\fR
-then the replacement of the old history database with the new one is
-assumed to be performed out of band by the caller. The \fIwriting\fR flag
-is normally passed as \fBtrue\fR, if you wish to inhibit writing of the
-new database (and so merely see the callbacks), \fIwriting\fR may be set
-\&\fBfalse\fR.
-.PP
-If the underlying history mechanism needs to pause the server, the
-\&\fIreason\fR 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 \fBHISexpire\fR; if the caller wishes to inhibit pausing of
-the server, passing \fB\s-1NULL\s0\fR will achieve this. If \fIreason\fR is not
-\&\fB\s-1NULL\s0\fR, then on successful return from \fBHISexpire\fR the server will
-be left paused and the caller should unpause it.
-.PP
-The history database is scanned and entries with an associated storage
-token are passed to the discrimination function \fIexists\fR.
-.PP
-If \fIexists\fR() returns \fBfalse\fR 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 \fIthreshold\fR constraint. If \fIexists\fR() returns \fBtrue\fR the
-entry is kept as-is in the newly expired history database.
-.PP
-The \fIexists\fR 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
-\&\fB\s-1NULL\s0\fR (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).
-.PP
-Entries in the database with an arrival time less than \fIthreshold\fR
-with no token associated with them are deleted from the database.
-.PP
-The parameter \fIcookie\fR is passed to the discrimination function, and
-may be used for any purpose required by the caller.
-.PP
-If the discrimination function attempts to access the underlying
-database (for read or write) during the callback, the behaviour is
-unspecified.
-.PP
-\&\fBHISwalk\fR provides an iteration function for the specified \fIhistory\fR
-database. For every entry in the history database, \fIcallback\fR is
-invoked, passing the \fIcookie\fR, arrival, posting, and expiry times, in
-addition to the token associated with the entry. If the \fIcallback\fR()
-returns \fBfalse\fR the iteration is aborted and \fBHISwalk\fR returns
-\&\fBfalse\fR to the caller.
-.PP
-To process the entire database in the presence of a running server,
-\&\fIreason\fR may be passed; if this argument is not \fB\s-1NULL\s0\fR, it is used
-as an an argument to the `ctlinnd (reserve|pause|go)' commands. If
-\&\fIreason\fR is \fB\s-1NULL\s0\fR and the server is running, the behaviour of
-\&\fBHISwalk\fR is undefined.
-.PP
-If the callback function attempts to access the underlying database
-during the callback, the behaviour is unspecified.
-.PP
-\&\fBHISstats\fR returns statistics on the history cache mechanism; given a
-handle \fIhistory\fR, the return value is a \fIstruct histstats\fR
-detailing:
-.ie n .IP """hitpos""" 4
-.el .IP "\f(CWhitpos\fR" 4
-.IX Item "hitpos"
-The number of times an item was found directly in the cache and known
-to exist in the underlying history manager.
-.ie n .IP """hitneg""" 4
-.el .IP "\f(CWhitneg\fR" 4
-.IX Item "hitneg"
-The number of times an item was found directly in the cache and known
-not to exist in the underlying history manager.
-.ie n .IP """misses""" 4
-.el .IP "\f(CWmisses\fR" 4
-.IX Item "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.
-.ie n .IP """dne""" 4
-.el .IP "\f(CWdne\fR" 4
-.IX Item "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.
-.PP
-Note that the history cache is only checked by \fBHIScheck\fR and only
-affected by \fBHIScheck\fR, \fBHISwrite\fR, \fBHISremember\fR and
-\&\fBHISreplace\fR. Following a call to \fBHISstats\fR the history statistics
-associated with \fIhistory\fR are cleared.
-.PP
-\&\fBHISerror\fR returns a string describing the most recent error
-associated with \fIhistory\fR; the format and content of these strings is
-history manager dependent. Note that on setting an error, the history
-\&\s-1API\s0 will call the \fBwarn\fR function from \fIlibinn\fR\|(3).
-.PP
-\&\fBHISctl\fR provides a control interface to the underlying history
-manager. The \fIrequest\fR argument determines the type of the request
-and the meaning of the \fIval\fR argument. The values for \fIrequest\fR are:
-.ie n .IP """HISCTLG_PATH"" (const char **)" 4
-.el .IP "\f(CWHISCTLG_PATH\fR (const char **)" 4
-.IX Item "HISCTLG_PATH (const char **)"
-Get the base file path which the history handle represents. \fIval\fR
-should be a pointer to a location of type \fBconst char *\fR. The
-result must not later be passed to \fIfree\fR\|(3).
-.ie n .IP """HISCTLS_PATH"" (const char *)" 4
-.el .IP "\f(CWHISCTLS_PATH\fR (const char *)" 4
-.IX Item "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
-\&\fBHISopen(\s-1NULL\s0, ...)\fR. \fIval\fR should be a value of type \fBconst char
-*\fR and will be copied before being stored internally.
-.ie n .IP """HISCTLS_SYNCCOUNT"" (size_t *)" 4
-.el .IP "\f(CWHISCTLS_SYNCCOUNT\fR (size_t *)" 4
-.IX Item "HISCTLS_SYNCCOUNT (size_t *)"
-Set an upper bound on how many history operations may be pending in
-core before being synced to permanent storage; \fB0\fR indicates
-unlimited. \fIval\fR should be a pointer to a value of type \fBsize_t\fR and
-will not be modified by the call.
-.ie n .IP """HISCTLS_NPAIRS"" (size_t *)" 4
-.el .IP "\f(CWHISCTLS_NPAIRS\fR (size_t *)" 4
-.IX Item "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; \fB0\fR
-indicates that an automatic or default sizing should be made. \fIval\fR
-should be a pointer to a value of type \fBsize_t\fR and will not be
-modified by the call.
-.ie n .IP """HISCTLS_IGNOREOLD"" (bool *)" 4
-.el .IP "\f(CWHISCTLS_IGNOREOLD\fR (bool *)" 4
-.IX Item "HISCTLS_IGNOREOLD (bool *)"
-Instruct the underlying history manager to ignore existing database
-when creating new ones; typically this option may be set to \fBtrue\fR if
-the administrator believes that the existing history database is
-corrupt and that ignoring it may help. \fIval\fR should be a pointer to a
-value of type \fBbool\fR and will not be modified by the call.
-.ie n .IP """HISCTLS_STATINTERVAL"" (time_t *)" 4
-.el .IP "\f(CWHISCTLS_STATINTERVAL\fR (time_t *)" 4
-.IX Item "HISCTLS_STATINTERVAL (time_t *)"
-For the history v6 and tagged hash managers, set the interval, in
-seconds, between \fIstat\fR\|(2)s of the history files checking for replaced
-files (as happens during expire); this option is typically used by
-\&\fInnrpd\fR\|(8) like applications. \fIval\fR should be a pointer to a value of
-type \fBtime_t\fR and will not be modified by the call.
-.SH "HISTORY"
-.IX Header "HISTORY"
-Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
-.Sp
-$Id: libinnhist.3 7880 2008-06-16 20:37:13Z iulius $
~ian / innduct.git / blobdiff