.\" Automatically generated by Pod::Man 4.07 (Pod::Simple 3.32) .\" .\" Standard preamble: .\" ======================================================================== .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" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .if !\nF .nr F 0 .if \nF>0 \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} .\} .\" .\" 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 "2018-05-14" "INN 2.6.3" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" his \- routines for managing INN history .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" These functions 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 specified 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 and also its posting time \fIposted\fR, if known. (Otherwise, its posting time may be specified as <= 0 in case it is absent.) \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 specified 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 be updated if required (for example, as might be needed by a hierarchical storage management implementation). .PP Entries in the database with a posting time less than \fIthreshold\fR with no token associated with them are deleted from the database. In case the posting time is unknown, the arrival time is used instead. .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 for InterNetNews\ 2.4.0. .PP \&\f(CW$Id:\fR libinnhist.pod 10283 2018\-05\-14 12:43:05Z iulius $