1libinnstorage(3) InterNetNews Documentation libinnstorage(3)
2
6 libinnstorage - Routines for managing INN storage
7
9 #include <inn/storage.h>
10 typedef enum {
12 RETR_ALL,
13 RETR_HEAD,
14 RETR_BODY,
15 RETR_STAT
16 } RETRTYPE;
17 typedef enum {
19 SM_RDWR,
20 SM_PREOPEN
21 } SMSETUP;
22 typedef unsigned char STORAGECLASS;
24 typedef unsigned char STORAGETYPE;
25 typedef struct token {
27 STORAGETYPE type;
28 STORAGECLASS class;
29 char token[STORAGE_TOKEN_LENGTH];
30 } TOKEN;
31 typedef struct {
33 unsigned char type;
34 const char *data;
35 struct iovec *iov;
36 int iovcnt;
37 size_t len;
38 unsigned char nextmethod;
39 void *private;
40 time_t arrived;
41 time_t expires;
42 char *groups;
43 int groupslen;
44 TOKEN *token;
45 } ARTHANDLE;
46 typedef enum {
48 SELFEXPIRE,
49 SMARTNGNUM,
50 EXPENSIVESTAT
51 } PROBETYPE;
52 typedef enum {
54 SM_ALL,
55 SM_HEAD,
56 SM_CANCELLEDART
57 } FLUSHTYPE;
58 struct artngnum {
60 char *groupname;
61 ARTNUM artnum;
62 };
63 bool IsToken(const char *text);
65 char *TokenToText(const TOKEN token);
67 TOKEN TextToToken(const char *text);
69 bool SMsetup(SMSETUP type, void *value);
71 bool SMinit(void);
73 TOKEN SMstore(const ARTHANDLE article);
75 ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);
77 ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);
79 void SMfreearticle(ARTHANDLE *article);
81 bool SMcancel(TOKEN token);
83 bool SMprobe(PROBETYPE type, TOKEN *token, void *value);
85 void SMprintfiles(FILE *file, TOKEN token, char **xref,
87 int ngroups);
88 bool SMflushcacheddata(FLUSHTYPE type);
90 char *SMexplaintoken(const TOKEN token);
92 void SMshutdown(void);
94 int SMerrno;
96 char *SMerrorstr;
98 #include <inn/ov.h>
100 #define OV_NOSPACE ...
102 typedef enum {
104 OVSPACE,
105 OVSORT,
106 OVCUTOFFLOW,
107 OVGROUPBASEDEXPIRE,
108 OVSTATICSEARCH,
109 OVSTATALL,
110 OVCACHEKEEP,
111 OVCACHEFREE
112 } OVCTLTYPE;
113 typedef enum {
115 OVNEWSGROUP,
116 OVARRIVED,
117 OVNOSORT
118 } OVSORTTYPE;
119 typedef enum {
121 OVADDCOMPLETED,
122 OVADDFAILED,
123 OVADDGROUPNOMATCH
124 } OVADDRESULT;
125 bool OVopen(int mode);
127 bool OVctl(OVCTLTYPE type, void *val);
129 bool OVgroupstats(char *group, int *lo, int *hi, int *count,
131 int *flag);
132 bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
134 bool OVgroupdel(char *group);
136 OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived,
138 time_t expires);
139 bool OVcancel(TOKEN token);
141 void *OVopensearch(char *group, int low, int high);
143 bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len,
145 TOKEN *token, time_t *arrived);
146 void OVclosesearch(void *handle);
148 bool OVgetartinfo(char *group, ARTNUM artnum, TOKEN *token);
150 bool OVexpiregroup(char *group, int *lo, struct history *h);
152 typedef struct _OVGE {
154 bool delayrm;
155 bool usepost;
156 bool quiet;
157 bool keep;
158 bool earliest;
159 bool ignoreselfexpire;
160 char *filename;
161 time_t now;
162 float timewarp;
163 } OVGE;
164 void OVclose(void);
166
168 libinnstorage is a library of common utility (the storage manager)
169 routines for accessing Usenet articles and related data independent of
170 particular storage method; this is known as the storage API.
171 The storage manager's function is to isolate the applications from the
173 individual methods and make the policy decisions as to which storage
174 method should be called to store an article. One of the core concepts
175 in the storage API is that articles are not manipulated using the
176 message-ID or article number, but rather a token that uniquely
177 identifies the article to the method that stored it. This may seem to
178 be redundant since the message-ID already is a unique identifier for
179 the article; however, since the storage method generates the token, it
180 can encode all the information it needs to locate the article in the
181 token.
182 OV is a common utility routines for accessing newsgroups and overview
184 data independent of particular overview method.
185 The OV function is to isolate the applications from the individual
187 methods. All articles passed through the storage API are assumed to be
188 in wire format. Wire format means "\r\n" at the end of lines, dot-
189 stuffed lines (that is to say "." at the beginning of lines which
190 already start with "."), and ".\r\n" at the end of article on NNTP
191 stream are not stripped. This has a performance win when transferring
192 articles. Note that for the tradspool method, wire format can be
193 disabled. This is just for compatibility which is needed by some old
194 tools written for traditional spool.
195 The IsToken function checks to see if the text is formatted as a text
197 token string. It returns true if formatted correctly or returns false
198 if not.
199 The TokenToText function converts a token into a text string for
201 output.
202 The TextToToken function converts a text string into a token.
204 The SMsetup function configures some parameters for use by the storage
206 manager. type is one of following:
207 "SM_RDWR"
209 Allow read/write open for storage files (default is false).
210 "SM_PREOPEN"
212 Open all storage files at startup time and keep them (default is
213 false).
214 value is the pointer which tells each type's value. It returns true if
216 setup is successful, or false if not.
217 The SMinit function calls the setup function for all of the configured
219 methods based on SMsetup. This function should be called prior to all
220 other storage API functions which begin with "SM" except SMsetup. It
221 returns true if initialization is successful or returns false if not.
222 SMinit returns true, unless all storage methods fail initialization.
223 The SMstore function stores an article specified with article. The
225 headers and body of the article are supplied to SMstore using the iov
226 and iovcnt members of ARTHANDLE. (data and private are ignored by
227 SMstore.) If arrived is specified, SMstore uses its value as article's
228 arrival time; otherwise SMstore uses the current time for it. SMstore
229 returns the token type or returns TOKEN_EMPTY if the article is not
230 stored because some error occurs or simply does not match any uwildmat
231 expression in storage.conf. SMstore fails if SM_RDWR has not been set
232 to true with SMsetup.
233 The SMretrieve function retrieves an article specified with token.
235 amount is the one of following which specifies retrieving type:
236 "RETR_ALL"
238 Retrieve the whole article.
239 "RETR_HEAD"
241 Retrieve the headers of the article.
242 "RETR_BODY"
244 Retrieve the body of the article.
245 "RETR_STAT"
247 Just check to see if the article exists.
248 SMretrieve provides the article data via the data and len members of
250 ARTHANDLE. (iov is not set by SMretrieve.) The data area indicated by
251 ARTHANDLE should not be modified.
252 The SMnext function is similar in function to SMretrieve except that it
254 is intended for traversing the method's article store sequentially. To
255 start a query, SMnext should be called with a NULL pointer ARTHANDLE.
256 Then SMnext returns ARTHANDLE which should be used for the next query.
257 If a NULL pointer ARTHANDLE is returned, no articles are left to be
258 queried. If data of ARTHANDLE is NULL pointer or len of ARTHANDLE is
259 0, it indicates the article may be corrupted and should be cancelled by
260 SMcancel. The data area indicated by ARTHANDLE should not be modified.
261 The SMfreearticle function frees all allocated memory used by
263 SMretrieve and SMnext. If SMnext will be called with previously
264 returned ARTHANDLE, SMfreearticle should not be called as SMnext frees
265 allocated memory internally.
266 The SMcancel function removes the article specified with token. It
268 returns true if cancellation is successful or returns false if not.
269 SMcancel fails if SM_RDWR has not been set to true with SMsetup.
270 The SMprobe function checks the token on PROBETYPE. type is one of
272 following:
273 "SELFEXPIRE"
275 Check to see if the method of the token has self expire
276 functionality.
277 "SMARTNGNUM"
279 Get the newsgroup name and the article number of the token.
280 "EXPENSIVESTAT"
282 Check to see whether checking the existence of an article is
283 expensive or not.
284 The SMprintfiles function shows file name or token usable by fastrm(1).
286 The SMflushcacheddata function flushes cached data on each storage
288 method. type is one of following:
289 "SM_HEAD"
291 Flush cached header.
292 "SM_CANCELLEDART"
294 Flush the articles which should be cancelled.
295 "SM_ALL"
297 Flush all cached data.
298 The SMexplaintoken function returns a human-readable text string with a
300 clear, decoded form of the storage API token.
301 The SMshutdown function calls the shutdown for each configured storage
303 method and then frees any resources it has allocated for itself.
304 SMerrno and SMerrorstr indicate the reason of the last error concerning
306 storage manager.
307 OVopen calls the setup function for configured method which is
309 specified as ovmethod in inn.conf. mode is constructed from following:
310 "OV_READ"
312 Allow read open for the overview method.
313 "OV_WRITE"
315 Allow write open for the overview method.
316 This function should be called prior to all other OV functions which
318 begin with "OV".
319 The OVctl function probes or sets some parameters for the overview
321 method. type is one of following:
322 "OVGROUPBASEDEXPIRE"
324 Setup how group-based expiry is done.
325 "OVCUTOFFLOW"
327 Do not add overview data if the data is under the lowest article.
328 "OVSORT"
330 Probe which key is suitable for the overview method.
331 "OVSPACE"
333 Probe the overview space usage.
334 "OVSTATALL"
336 Stat all the articles when OVexpiregroup is called.
337 "OVSTATICSEARCH"
339 Setup if results of OVsearch are stored in a static buffer and must
340 be copied before the next call to OVsearch.
341 "OVCACHEKEEP"
343 Setup whether the cache should be kept.
344 "OVCACHEFREE"
346 Free the cache.
347 The OVgroupstats function retrieves the specified newsgroup information
349 from the overview method.
350 The OVgroupadd function informs the overview method that the specified
352 newsgroup is being added.
353 The OVgroupdel function informs the overview method that the specified
355 newsgroup is being removed.
356 The OVadd function stores an overview data.
358 The OVcancel function requests the overview method delete overview data
360 specified with token.
361 The OVopensearch function requests the overview method prepare overview
363 data retrieval. The request range is determined by low and high. The
364 setting of OVSTATICSEARCH determines how search result data must be
365 handled. (Note that with some storage methods, each call to
366 OVopensearch may cause internal storage to be remapped. Therefore,
367 multiple simultaneous searches may require data to be copied in between
368 OVsearch calls even if OVSTATICSEARCH is false.)
369 The OVsearch function retrieves information, article number, overview
371 data, or arrival time. It should be called with NULL handle when it is
372 the first time; subsequent OVsearch calls should use the handle
373 returned by the previous call to OVsearch. OVsearch returns true,
374 unless it reaches high, which is specified by OVopensearch. Retrieved
375 overview data are sorted by article number, and len is 0 if there is no
376 overview data for the article. Note that the retrieved data is not
377 necessarily null-terminated; you should only rely on len octets of
378 overview data being present.
379 The OVclosesearch function frees all resources which have been
381 allocated by OVopensearch.
382 The OVgetartinfo function retrieves the overview data and the token
384 specified with artnum.
385 The OVexpiregroup function expires the overview data for the newsgroup.
387 It checks the existence of the article and purges the overview data if
388 the article no longer exists. If groupbaseexpiry in inn.conf is true,
389 OVexpiregroup also expires articles.
390 The OVclose function frees all resources which are used by the overview
392 method.
393
395 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
396 Converted to POD by Julien Elie.
397
399 expire(8), fastrm(1), inn.conf(5), libinn_uwildmat(3), storage.conf(5).
400INN 2.7.1 2023-03-07 libinnstorage(3)