1libinnhist(3) InterNetNews Documentation libinnhist(3)
2
6 his - routines for managing INN history
7
9 #include <inn/history.h>
10 struct history;
12 struct histstats { int hitpos; int hitneg; int misses;
14 int dne; };
15 #define HIS_RDONLY ... #define HIS_RDWR ... #define HIS_CREAT ...
17 #define HIS_ONDISK ... #define HIS_INCORE ... #define HIS_MMAP ...
18 enum { HISCTLG_PATH, HISCTLS_PATH, HISCTLS_SYNCCOUNT,
20 HISCTLS_NPAIRS, HISCTLS_IGNOREOLD, HISCTLS_STATINTERVAL };
21 struct history *HISopen(const char *path, const char *method, int
23 flags);
24 bool HISclose(struct history *history);
26 bool HISsync(struct history *history);
28 void HISsetcache(struct history *history, size_t size);
30 bool HISlookup(struct history *history, const char *key, time_t
32 *arrived, time_t *posted, time_t *expires, TOKEN *token);
33 bool HIScheck(struct history *history, const char *key);
35 bool HISwrite(struct history *history, const char *key, time_t arrived,
37 time_t posted, time_t expires, const TOKEN *token);
38 bool HISremember(struct history *history, const char *key, time_t
40 arrived);
41 bool HISreplace(struct history *history, const char *key, time_t
43 arrived, time_t posted, time_t expires, const TOKEN *token);
44 bool HISexpire(struct history *history, const char *path, const char
46 *reason, bool writing, void *cookie, time_t threshold, bool
47 (*exists)(void *cookie, time_t arrived, time_t posted, time_t expires,
48 const TOKEN *token));
49 bool HISwalk(struct history *history, const char *reason, void *cookie,
51 bool (*callback)(void *cookie, time_t arrived, time_t posted, time_t
52 expires, const TOKEN *token));
53 struct histstats HISstats(struct history *history);
55 const char *HISerror(struct history *history);
57 bool HISctl(struct history *history, int request, void *val);
59
61 These functions provide provide access to the INN history database.
62 They maintain key/value pairs in an opaque database whilst providing
63 for expiry of outdated information.
64 The history structure is an opaque handle returned from HISopen.
66 The HISopen function opens the history file designated by path using
68 the mode flags using the specified method. flags may be HIS_RDONLY to
69 indicate that read-only access to the history database is desired, or
70 HIS_RDWR for read/write access. History methods are defined at build
71 time; the history method currently available is "hisv6". On success a
72 newly initialised history handle is returned, or NULL on failure.
73 HIS_ONDISK, HIS_INCORE and HIS_MMAP may be logically ORed into flags to
75 provide a hint to the underlying history manager as to how it should
76 handle its data files; HIS_ONDISK indicates that the caller would like
77 as much of the data to be kept on disk (and out of memory), HIS_INCORE
78 indicates that the data files should be kept in main memory where pos‐
79 sible and HIS_MMAP that the files should be mmap()ed into the processes
80 address space. HIS_INCORE is typically used where a mass rebuild of the
81 history database is being performed; the underlying history manager may
82 assume that the caller will call HISsync() to sync the data files to
83 disk.
84 The HIS_CREAT flag indicates that the history database should be ini‐
86 tialised as new; if any options which affect creation of the database
87 need to be set an anonymous history handle should be created by calling
88 HISopen with path set to NULL, any options set using HISctl, then the
89 database opened by calling HISctl with HISCTLS_PATH.
90 The HISclose function closes the handle history and deallocates any
92 resources associated with it. It returns false on failure or true on
93 success.
94 The HISsync function synchronises any outstanding transactions associ‐
96 ated with history to disk.
97 HISsetcache associates a cache used for speeding up HIScheck with his‐
99 tory. The cache will occupy approximately size bytes.
100 HISlookup retrieves a token from history based on the passed key (nor‐
102 mally the Message-ID). If no entry with an associated token can be
103 found, HISlookup will return false. If a token is found arrived,
104 expires, and posted are filled in with the message arrival, expiry, and
105 posting times respectively (or zero, if the time component is not
106 available), in addition to token being set to the retrieved token and a
107 function return value of true. Any of arrived, expires, posted, or
108 token may be NULL in which case that component is not returned to the
109 caller, without affecting the return value.
110 HIScheck checks the database history for key (normally the Message-ID);
112 if key has previously been set via HISwrite, HIScheck returns true,
113 else false.
114 HISwrite writes a new entry to the database history associated with
116 key. arrived, posted, and expired specify the arrival, posting, and
117 expiry time respectively; posted and expired may be specifed as <= 0 in
118 which case that component shall be treated as absent in the database.
119 token is associated with the specified key. HISwrite returns true on
120 success, or false on failure. The behaviour when key is not unique with
121 respect to the existing entries in history is unspecified.
122 HISremember writes a new entry to the database history associated with
124 key, merely remembering that this key has been seen, together with its
125 arrival time arrived. HISremember returns true on success, or false on
126 failure. The behaviour when key is not unique with respect to the
127 existing entries in history is unspecified.
128 HISreplace replaces an existing entry in the database history, associ‐
130 ated with key. arrived, posted, expired specify the arrival, posting
131 and expiry time respectively; posted and expired may be specifed as <=
132 0 in which case that component shall be treated as absent in the data‐
133 base. token is associated with the specified key; if NULL then the his‐
134 tory database merely remembers that this key has been seen, together
135 with its arrival time. HISreplace returns true on success, or false on
136 failure.
137 HISexpire expires the history database associated with history, creat‐
139 ing a new, replacement, database in the same location if path is NULL,
140 or in path if not NULL; if path is not NULL then the replacement of the
141 old history database with the new one is assumed to be performed out of
142 band by the caller. The writing flag is normally passed as true, if you
143 wish to inhibit writing of the new database (and so merely see the
144 callbacks), writing may be set false.
145 If the underlying history mechanism needs to pause the server, the rea‐
147 son string is used as the argument to the `ctlinnd pause' command, and
148 as such the server should be reserved by the caller prior to calling
149 HISexpire; if the caller wishes to inhibit pausing of the server, pass‐
150 ing NULL will achieve this. If reason is not NULL, then on successful
151 return from HISexpire the server will be left paused and the caller
152 should unpause it.
153 The history database is scanned and entries with an associated storage
155 token are passed to the discrimination function exists.
156 If exists() returns false it indicates that stored entity associated
158 with token is no longer available (or no longer required), and there‐
159 fore the associated history entry may be expired once it meets the
160 threshold constraint. If exists() returns true the entry is kept as-is
161 in the newly expired history database.
162 The exists function is passed the arrival, posting and expiry times, in
164 addition to the token associated with the entry. Note that posting
165 and/or expiry may be zero, but that the token will never be NULL (such
166 entries are handled solely via the threshold mechanism). The storage
167 token passed to the discrimination function may updated if required
168 (for example, as might be needed by a hierachical storage management
169 implementation).
170 Entries in the database with an arrival time less than threshold with
172 no token associated with them are deleted from the database.
173 The parameter cookie is passed to the discrimination function, and may
175 be used for any purpose required by the caller.
176 If the discrimination function attempts to access the underlying data‐
178 base (for read or write) during the callback, the behaviour is unspeci‐
179 fied.
180 HISwalk provides an iteration function for the specified history data‐
182 base. For every entry in the history database, callback is invoked,
183 passing the cookie, arrival, posting, and expiry times, in addition to
184 the token associated with the entry. If the callback() returns false
185 the iteration is aborted and HISwalk returns false to the caller.
186 To process the entire database in the presence of a running server,
188 reason may be passed; if this argument is not NULL, it is used as an an
189 argument to the `ctlinnd (reserve⎪pause⎪go)' commands. If reason is
190 NULL and the server is running, the behaviour of HISwalk is undefined.
191 If the callback function attempts to access the underlying database
193 during the callback, the behaviour is unspecified.
194 HISstats returns statistics on the history cache mechanism; given a
196 handle history, the return value is a struct histstats detailing:
197 "hitpos"
199 The number of times an item was found directly in the cache and
200 known to exist in the underlying history manager.
201 "hitneg"
203 The number of times an item was found directly in the cache and
204 known not to exist in the underlying history manager.
205 "misses"
207 The number of times an item was not found directly in the cache,
208 but on retrieval from the underlying history manager was found to
209 exist.
210 "dne"
212 The number of times an item was not found directly in the cache,
213 but on retrieval from the underlying history manager was found not
214 to exist.
215 Note that the history cache is only checked by HIScheck and only
217 affected by HIScheck, HISwrite, HISremember and HISreplace. Following a
218 call to HISstats the history statistics associated with history are
219 cleared.
220 HISerror returns a string describing the most recent error associated
222 with history; the format and content of these strings is history man‐
223 ager dependent. Note that on setting an error, the history API will
224 call the warn function from libinn(3).
225 HISctl provides a control interface to the underlying history manager.
227 The request argument determines the type of the request and the meaning
228 of the val argument. The values for request are:
229 "HISCTLG_PATH" (const char **)
231 Get the base file path which the history handle represents. val
232 should be a pointer to a location of type const char *. The result
233 must not later be passed to free(3).
234 "HISCTLS_PATH" (const char *)
236 Set the base file path which this history handle should use; typi‐
237 cally this is used after an anonymous handle has been created using
238 HISopen(NULL, ...). val should be a value of type const char * and
239 will be copied before being stored internally.
240 "HISCTLS_SYNCCOUNT" (size_t *)
242 Set an upper bound on how many history operations may be pending in
243 core before being synced to permanent storage; 0 indicates unlim‐
244 ited. val should be a pointer to a value of type size_t and will
245 not be modified by the call.
246 "HISCTLS_NPAIRS" (size_t *)
248 Set a hint to the to the underlying history manager as to how many
249 entries there are expected to be in the history database; 0 indi‐
250 cates that an automatic or default sizing should be made. val
251 should be a pointer to a value of type size_t and will not be modi‐
252 fied by the call.
253 "HISCTLS_IGNOREOLD" (bool *)
255 Instruct the underlying history manager to ignore existing database
256 when creating new ones; typically this option may be set to true if
257 the administrator believes that the existing history database is
258 corrupt and that ignoring it may help. val should be a pointer to a
259 value of type bool and will not be modified by the call.
260 "HISCTLS_STATINTERVAL" (time_t *)
262 For the history v6 and tagged hash managers, set the interval, in
263 seconds, between stat(2)s of the history files checking for
264 replaced files (as happens during expire); this option is typically
265 used by nnrpd(8) like applications. val should be a pointer to a
266 value of type time_t and will not be modified by the call.
267
269 Written by Alex Kiernan <alexk@demon.net> for InterNetNews 2.4.0.
270 $Id: libinnhist.3 5912 2002-12-03 05:31:11Z vinocur $
272INN 2.4.0 2002-12-03 libinnhist(3)