1libinnhist(3)             InterNetNews Documentation             libinnhist(3)
2
3
4

NAME

6       his - routines for managing INN history
7

SYNOPSIS

9           #include <inn/history.h>
10
11           struct history;
12           struct token;
13
14           struct histstats {
15               int hitpos;
16               int hitneg;
17               int misses;
18               int dne;
19           };
20
21           #define HIS_RDONLY ...
22           #define HIS_RDWR ...
23           #define HIS_CREAT ...
24           #define HIS_ONDISK ...
25           #define HIS_INCORE ...
26           #define HIS_MMAP ...
27
28           enum {
29               HISCTLG_PATH,
30               HISCTLS_PATH,
31               HISCTLS_SYNCCOUNT,
32               HISCTLS_NPAIRS,
33               HISCTLS_IGNOREOLD,
34               HISCTLS_STATINTERVAL
35           };
36
37           struct history *HISopen(const char *path, const char *method, int flags);
38
39           bool HISclose(struct history *history);
40
41           bool HISsync(struct history *history);
42
43           void HISsetcache(struct history *history, size_t size);
44
45           bool HISlookup(struct history *history, const char *key, time_t *arrived, time_t *posted, time_t *expires, TOKEN *token);
46
47           bool HIScheck(struct history *history, const char *key);
48
49           bool HISwrite(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);
50
51           bool HISremember(struct history *history, const char *key, time_t arrived, time_t posted);
52
53           bool HISreplace(struct history *history, const char *key, time_t arrived, time_t posted, time_t expires, const TOKEN *token);
54
55           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));
56
57           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));
58
59           struct histstats HISstats(struct history *history);
60
61           const char *HISerror(struct history *history);
62
63           bool HISctl(struct history *history, int request, void *val);
64

DESCRIPTION

66       These functions provide access to the INN history database.  They
67       maintain key/value pairs in an opaque database whilst providing for
68       expiry of outdated information.
69
70       The history structure is an opaque handle returned from HISopen.
71
72       The HISopen function opens the history file designated by path using
73       the mode flags using the specified method. flags may be HIS_RDONLY to
74       indicate that read-only access to the history database is desired, or
75       HIS_RDWR for read/write access. History methods are defined at build
76       time; the history method currently available is "hisv6". On success a
77       newly initialised history handle is returned, or NULL on failure.
78
79       HIS_ONDISK, HIS_INCORE and HIS_MMAP may be logically ORed into flags to
80       provide a hint to the underlying history manager as to how it should
81       handle its data files; HIS_ONDISK indicates that the caller would like
82       as much of the data to be kept on disk (and out of memory), HIS_INCORE
83       indicates that the data files should be kept in main memory where
84       possible and HIS_MMAP that the files should be mmap()ed into the
85       processes address space. HIS_INCORE is typically used where a mass
86       rebuild of the history database is being performed; the underlying
87       history manager may assume that the caller will call HISsync() to sync
88       the data files to disk.
89
90       The HIS_CREAT flag indicates that the history database should be
91       initialised as new; if any options which affect creation of the
92       database need to be set an anonymous history handle should be created
93       by calling HISopen with path set to NULL, any options set using HISctl,
94       then the database opened by calling HISctl with HISCTLS_PATH.
95
96       The HISclose function closes the handle history and deallocates any
97       resources associated with it. It returns false on failure or true on
98       success.
99
100       The HISsync function synchronises any outstanding transactions
101       associated with history to disk.
102
103       HISsetcache associates a cache used for speeding up HIScheck with
104       history. The cache will occupy approximately size bytes.
105
106       HISlookup retrieves a token from history based on the passed key
107       (normally the Message-ID). If no entry with an associated token can be
108       found, HISlookup will return false. If a token is found arrived,
109       expires, and posted are filled in with the message arrival, expiry, and
110       posting times respectively (or zero, if the time component is not
111       available), in addition to token being set to the retrieved token and a
112       function return value of true. Any of arrived, expires, posted, or
113       token may be NULL in which case that component is not returned to the
114       caller, without affecting the return value.
115
116       HIScheck checks the database history for key (normally the Message-ID);
117       if key has previously been set via HISwrite, HIScheck returns true,
118       else false.
119
120       HISwrite writes a new entry to the database history associated with
121       key. arrived, posted, and expired specify the arrival, posting, and
122       expiry time respectively; posted and expired may be specified as <= 0
123       in which case that component shall be treated as absent in the
124       database. token is associated with the specified key. HISwrite returns
125       true on success, or false on failure. The behaviour when key is not
126       unique with respect to the existing entries in history is unspecified.
127
128       HISremember writes a new entry to the database history associated with
129       key, merely remembering that this key has been seen, together with its
130       arrival time arrived and also its posting time posted, if known.
131       (Otherwise, its posting time may be specified as <= 0 in case it is
132       absent.)  HISremember returns true on success, or false on failure.
133       The behaviour when key is not unique with respect to the existing
134       entries in history is unspecified.
135
136       HISreplace replaces an existing entry in the database history,
137       associated with key. arrived, posted, expired specify the arrival,
138       posting and expiry time respectively; posted and expired may be
139       specified as <= 0 in which case that component shall be treated as
140       absent in the database. token is associated with the specified key; if
141       NULL then the history database merely remembers that this key has been
142       seen, together with its arrival time. HISreplace returns true on
143       success, or false on failure.
144
145       HISexpire expires the history database associated with history,
146       creating a new, replacement, database in the same location if path is
147       NULL, or in path if not NULL; if path is not NULL then the replacement
148       of the old history database with the new one is assumed to be performed
149       out of band by the caller. The writing flag is normally passed as true,
150       if you wish to inhibit writing of the new database (and so merely see
151       the callbacks), writing may be set false.
152
153       If the underlying history mechanism needs to pause the server, the
154       reason string is used as the argument to the `ctlinnd pause' command,
155       and as such the server should be reserved by the caller prior to
156       calling HISexpire; if the caller wishes to inhibit pausing of the
157       server, passing NULL will achieve this. If reason is not NULL, then on
158       successful return from HISexpire the server will be left paused and the
159       caller should unpause it.
160
161       The history database is scanned and entries with an associated storage
162       token are passed to the discrimination function exists.
163
164       If exists() returns false it indicates that stored entity associated
165       with token is no longer available (or no longer required), and
166       therefore the associated history entry may be expired once it meets the
167       threshold constraint. If exists() returns true the entry is kept as-is
168       in the newly expired history database.
169
170       The exists function is passed the arrival, posting and expiry times, in
171       addition to the token associated with the entry. Note that posting
172       and/or expiry may be zero, but that the token will never be NULL (such
173       entries are handled solely via the threshold mechanism). The storage
174       token passed to the discrimination function may be updated if required
175       (for example, as might be needed by a hierarchical storage management
176       implementation).
177
178       Entries in the database with a posting time less than threshold with no
179       token associated with them are deleted from the database.  In case the
180       posting time is unknown, the arrival time is used instead.
181
182       The parameter cookie is passed to the discrimination function, and may
183       be used for any purpose required by the caller.
184
185       If the discrimination function attempts to access the underlying
186       database (for read or write) during the callback, the behaviour is
187       unspecified.
188
189       HISwalk provides an iteration function for the specified history
190       database. For every entry in the history database, callback is invoked,
191       passing the cookie, arrival, posting, and expiry times, in addition to
192       the token associated with the entry. If the callback() returns false
193       the iteration is aborted and HISwalk returns false to the caller.
194
195       To process the entire database in the presence of a running server,
196       reason may be passed; if this argument is not NULL, it is used as an an
197       argument to the `ctlinnd (reserve|pause|go)' commands. If reason is
198       NULL and the server is running, the behaviour of HISwalk is undefined.
199
200       If the callback function attempts to access the underlying database
201       during the callback, the behaviour is unspecified.
202
203       HISstats returns statistics on the history cache mechanism; given a
204       handle history, the return value is a struct histstats detailing:
205
206       "hitpos"
207           The number of times an item was found directly in the cache and
208           known to exist in the underlying history manager.
209
210       "hitneg"
211           The number of times an item was found directly in the cache and
212           known not to exist in the underlying history manager.
213
214       "misses"
215           The number of times an item was not found directly in the cache,
216           but on retrieval from the underlying history manager was found to
217           exist.
218
219       "dne"
220           The number of times an item was not found directly in the cache,
221           but on retrieval from the underlying history manager was found not
222           to exist.
223
224       Note that the history cache is only checked by HIScheck and only
225       affected by HIScheck, HISwrite, HISremember and HISreplace. Following a
226       call to HISstats the history statistics associated with history are
227       cleared.
228
229       HISerror returns a string describing the most recent error associated
230       with history; the format and content of these strings is history
231       manager dependent. Note that on setting an error, the history API will
232       call the warn function from libinn(3).
233
234       HISctl provides a control interface to the underlying history manager.
235       The request argument determines the type of the request and the meaning
236       of the val argument. The values for request are:
237
238       "HISCTLG_PATH" (const char **)
239           Get the base file path which the history handle represents. val
240           should be a pointer to a location of type const char *.  The result
241           must not later be passed to free(3).
242
243       "HISCTLS_PATH" (const char *)
244           Set the base file path which this history handle should use;
245           typically this is used after an anonymous handle has been created
246           using HISopen(NULL, ...). val should be a value of type const char
247           * and will be copied before being stored internally.
248
249       "HISCTLS_SYNCCOUNT" (size_t *)
250           Set an upper bound on how many history operations may be pending in
251           core before being synced to permanent storage; 0 indicates
252           unlimited. val should be a pointer to a value of type size_t and
253           will not be modified by the call.
254
255       "HISCTLS_NPAIRS" (size_t *)
256           Set a hint to the to the underlying history manager as to how many
257           entries there are expected to be in the history database; 0
258           indicates that an automatic or default sizing should be made. val
259           should be a pointer to a value of type size_t and will not be
260           modified by the call.
261
262       "HISCTLS_IGNOREOLD" (bool *)
263           Instruct the underlying history manager to ignore existing database
264           when creating new ones; typically this option may be set to true if
265           the administrator believes that the existing history database is
266           corrupt and that ignoring it may help. val should be a pointer to a
267           value of type bool and will not be modified by the call.
268
269       "HISCTLS_STATINTERVAL" (time_t *)
270           For the history v6 and tagged hash managers, set the interval, in
271           seconds, between stat(2)s of the history files checking for
272           replaced files (as happens during expire); this option is typically
273           used by nnrpd(8) like applications. val should be a pointer to a
274           value of type time_t and will not be modified by the call.
275

HISTORY

277       Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
278
279       $Id: libinnhist.pod 10283 2018-05-14 12:43:05Z iulius $
280
281
282
283INN 2.6.3                         2018-05-14                     libinnhist(3)
Impressum