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