1libstorage(3) InterNetNews Documentation libstorage(3)
2
6 libstorage - 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, int ngroups);
87 bool SMflushcacheddata(FLUSHTYPE type);
89 char *SMexplaintoken(const TOKEN token);
91 void SMshutdown(void);
93 int SMerrno;
95 char *SMerrorstr;
97 #include <inn/ov.h>
99 #define OV_NOSPACE ...
101 typedef enum {
103 OVSPACE,
104 OVSORT,
105 OVCUTOFFLOW,
106 OVGROUPBASEDEXPIRE,
107 OVSTATICSEARCH,
108 OVSTATALL,
109 OVCACHEKEEP,
110 OVCACHEFREE
111 } OVCTLTYPE;
112 typedef enum {
114 OVNEWSGROUP,
115 OVARRIVED,
116 OVNOSORT
117 } OVSORTTYPE;
118 typedef enum {
120 OVADDCOMPLETED,
121 OVADDFAILED,
122 OVADDGROUPNOMATCH
123 } OVADDRESULT;
124 bool OVopen(int mode);
126 bool OVctl(OVCTLTYPE type, void *val);
128 bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);
130 bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
132 bool OVgroupdel(char *group);
134 OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived, time_t expires);
136 bool OVcancel(TOKEN token);
138 void *OVopensearch(char *group, int low, int high);
140 bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);
142 void OVclosesearch(void *handle);
144 bool OVgetartinfo(char *group, ARTNUM artnum, TOKEN *token);
146 bool OVexpiregroup(char *group, int *lo, struct history *h);
148 typedef struct _OVGE {
150 bool delayrm;
151 bool usepost;
152 bool quiet;
153 bool keep;
154 bool earliest;
155 bool ignoreselfexpire;
156 char *filename;
157 time_t now;
158 float timewarp;
159 } OVGE;
160 void OVclose(void);
162
164 libstorage is a library of common utility (the storage manager)
165 routines for accessing Usenet articles and related data independent of
166 particular storage method; this is known as the storage API.
167 The storage manager's function is to isolate the applications from the
169 individual methods and make the policy decisions as to which storage
170 method should be called to store an article. One of the core concepts
171 in the storage API is that articles are not manipulated using the
172 message-ID or article number, but rather a token that uniquely
173 identifies the article to the method that stored it. This may seem to
174 be redundant since the message-ID already is a unique identifier for
175 the article; however, since the storage method generates the token, it
176 can encode all the information it needs to locate the article in the
177 token.
178 OV is a common utility routines for accessing newsgroups and overview
180 data independent of particular overview method.
181 The OV function is to isolate the applications from the individual
183 methods. All articles passed through the storage API are assumed to be
184 in wire format. Wire format means "\r\n" at the end of lines, dot-
185 stuffed lines (that is to say "." at the beginning of lines which
186 already start with "."), and ".\r\n" at the end of article on NNTP
187 stream are not stripped. This has a performance win when transferring
188 articles. Note that for the tradspool method, wire format can be
189 disabled. This is just for compatibility which is needed by some old
190 tools written for traditional spool.
191 The IsToken function checks to see if the text is formatted as a text
193 token string. It returns true if formatted correctly or returns false
194 if not.
195 The TokenToText function converts a token into a text string for
197 output.
198 The TextToToken function converts a text string into a token.
200 The SMsetup function configures some parameters for use by the storage
202 manager. type is one of following:
203 "SM_RDWR"
205 Allow read/write open for storage files (default is false).
206 "SM_PREOPEN"
208 Open all storage files at startup time and keep them (default is
209 false).
210 value is the pointer which tells each type's value. It returns true if
212 setup is successful, or false if not.
213 The SMinit function calls the setup function for all of the configured
215 methods based on SMsetup. This function should be called prior to all
216 other storage API functions which begin with "SM" except SMsetup. It
217 returns true if initialization is successful or returns false if not.
218 SMinit returns true, unless all storage methods fail initialization.
219 The SMstore function stores an article specified with article. The
221 headers and body of the article are supplied to SMstore using the iov
222 and iovcnt members of ARTHANDLE. (data and private are ignored by
223 SMstore.) If arrived is specified, SMstore uses its value as article's
224 arrival time; otherwise SMstore uses the current time for it. SMstore
225 returns the token type or returns TOKEN_EMPTY if the article is not
226 stored because some error occurs or simply does not match any uwildmat
227 expression in storage.conf. SMstore fails if SM_RDWR has not been set
228 to true with SMsetup.
229 The SMretrieve function retrieves an article specified with token.
231 amount is the one of following which specifies retrieving type:
232 "RETR_ALL"
234 Retrieve the whole article.
235 "RETR_HEAD"
237 Retrieve the headers of the article.
238 "RETR_BODY"
240 Retrieve the body of the article.
241 "RETR_STAT"
243 Just check to see if the article exists.
244 SMretrieve provides the article data via the data and len members of
246 ARTHANDLE. (iov is not set by SMretrieve.) The data area indicated by
247 ARTHANDLE should not be modified.
248 The SMnext function is similar in function to SMretrieve except that it
250 is intended for traversing the method's article store sequentially. To
251 start a query, SMnext should be called with a NULL pointer ARTHANDLE.
252 Then SMnext returns ARTHANDLE which should be used for the next query.
253 If a NULL pointer ARTHANDLE is returned, no articles are left to be
254 queried. If data of ARTHANDLE is NULL pointer or len of ARTHANDLE is
255 0, it indicates the article may be corrupted and should be cancelled by
256 SMcancel. The data area indicated by ARTHANDLE should not be modified.
257 The SMfreearticle function frees all allocated memory used by
259 SMretrieve and SMnext. If SMnext will be called with previously
260 returned ARTHANDLE, SMfreearticle should not be called as SMnext frees
261 allocated memory internally.
262 The SMcancel function removes the article specified with token. It
264 returns true if cancellation is successful or returns false if not.
265 SMcancel fails if SM_RDWR has not been set to true with SMsetup.
266 The SMprobe function checks the token on PROBETYPE. type is one of
268 following:
269 "SELFEXPIRE"
271 Check to see if the method of the token has self expire
272 functionality.
273 "SMARTNGNUM"
275 Get the newsgroup name and the article number of the token.
276 "EXPENSIVESTAT"
278 Check to see whether checking the existence of an article is
279 expensive or not.
280 The SMprintfiles function shows file name or token usable by fastrm(8).
282 The SMflushcacheddata function flushes cached data on each storage
284 method. type is one of following:
285 "SM_HEAD"
287 Flush cached header.
288 "SM_CANCELLEDART"
290 Flush the articles which should be cancelled.
291 "SM_ALL"
293 Flush all cached data.
294 The SMexplaintoken function returns a human-readable text string with a
296 clear, decoded form of the storage API token.
297 The SMshutdown function calls the shutdown for each configured storage
299 method and then frees any resources it has allocated for itself.
300 SMerrno and SMerrorstr indicate the reason of the last error concerning
302 storage manager.
303 OVopen calls the setup function for configured method which is
305 specified as ovmethod in inn.conf. mode is constructed from following:
306 "OV_READ"
308 Allow read open for the overview method.
309 "OV_WRITE"
311 Allow write open for the overview method.
312 This function should be called prior to all other OV functions which
314 begin with "OV".
315 The OVctl function probes or sets some parameters for the overview
317 method. type is one of following:
318 "OVGROUPBASEDEXPIRE"
320 Setup how group-based expiry is done.
321 "OVCUTOFFLOW"
323 Do not add overview data if the data is under the lowest article.
324 "OVSORT"
326 Probe which key is suitable for the overview method.
327 "OVSPACE"
329 Probe the overview space usage.
330 "OVSTATALL"
332 Stat all the articles when OVexpiregroup is called.
333 "OVSTATICSEARCH"
335 Setup if results of OVsearch are stored in a static buffer and must
336 be copied before the next call to OVsearch.
337 "OVCACHEKEEP"
339 Setup whether the cache should be kept.
340 "OVCACHEFREE"
342 Free the cache.
343 The OVgroupstats function retrieves the specified newsgroup information
345 from the overview method.
346 The OVgroupadd function informs the overview method that the specified
348 newsgroup is being added.
349 The OVgroupdel function informs the overview method that the specified
351 newsgroup is being removed.
352 The OVadd function stores an overview data.
354 The OVcancel function requests the overview method delete overview data
356 specified with token.
357 The OVopensearch function requests the overview method prepare overview
359 data retrieval. The request range is determined by low and high. The
360 setting of OVSTATICSEARCH determines how search result data must be
361 handled. (Note that with some storage methods, each call to
362 OVopensearch may cause internal storage to be remapped. Therefore,
363 multiple simultaneous searches may require data to be copied in between
364 OVsearch calls even if OVSTATICSEARCH is false.)
365 The OVsearch function retrieves information, article number, overview
367 data, or arrival time. It should be called with NULL handle when it is
368 the first time; subsequent OVsearch calls should use the handle
369 returned by the previous call to OVsearch. OVsearch returns true,
370 unless it reaches high, which is specified by OVopensearch. Retrieved
371 overview data are sorted by article number, and len is 0 if there is no
372 overview data for the article. Note that the retrieved data is not
373 necessarily null-terminated; you should only rely on len octets of
374 overview data being present.
375 The OVclosesearch function frees all resources which have been
377 allocated by OVopensearch.
378 The OVgetartinfo function retrieves the overview data and the token
380 specified with artnum.
381 The OVexpiregroup function expires the overview data for the newsgroup.
383 It checks the existence of the article and purges the overview data if
384 the article no longer exists. If groupbaseexpiry in inn.conf is true,
385 OVexpiregroup also expires articles.
386 The OVclose function frees all resources which are used by the overview
388 method.
389
391 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
392 Converted to POD by Julien Elie.
393
395 expire(8), fastrm(8), inn.conf(5), libinn_uwildmat(3), storage.conf(5).
396INN 2.6.5 2022-02-18 libstorage(3)