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

NAME

6       libstorage - routines for managing INN storage
7

SYNOPSIS

9           #include <inn/storage.h>
10
11           typedef enum {
12               RETR_ALL,
13               RETR_HEAD,
14               RETR_BODY,
15               RETR_STAT
16           } RETRTYPE;
17
18           typedef enum {
19               SM_RDWR,
20               SM_PREOPEN
21           } SMSETUP;
22
23           typedef unsigned char STORAGECLASS;
24           typedef unsigned char STORAGETYPE;
25
26           typedef struct token {
27               STORAGETYPE  type;
28               STORAGECLASS class;
29               char         token[STORAGE_TOKEN_LENGTH];
30           } TOKEN;
31
32           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
47           typedef enum {
48               SELFEXPIRE,
49               SMARTNGNUM,
50               EXPENSIVESTAT
51           } PROBETYPE;
52
53           typedef enum {
54               SM_ALL,
55               SM_HEAD,
56               SM_CANCELLEDART
57           } FLUSHTYPE;
58
59           struct artngnum {
60               char   *groupname;
61               ARTNUM artnum;
62           };
63
64           bool IsToken(const char *text);
65
66           char *TokenToText(const TOKEN token);
67
68           TOKEN TextToToken(const char *text);
69
70           bool SMsetup(SMSETUP type, void *value);
71
72           bool SMinit(void);
73
74           TOKEN SMstore(const ARTHANDLE article);
75
76           ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);
77
78           ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);
79
80           void SMfreearticle(ARTHANDLE *article);
81
82           bool SMcancel(TOKEN token);
83
84           bool SMprobe(PROBETYPE type, TOKEN *token, void *value);
85
86           void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups);
87
88           bool SMflushcacheddata(FLUSHTYPE type);
89
90           char *SMexplaintoken(const TOKEN token);
91
92           void SMshutdown(void);
93
94           int SMerrno;
95
96           char *SMerrorstr;
97
98           #include <inn/ov.h>
99
100           #define OV_NOSPACE ...
101
102           typedef enum {
103               OVSPACE,
104               OVSORT,
105               OVCUTOFFLOW,
106               OVGROUPBASEDEXPIRE,
107               OVSTATICSEARCH,
108               OVSTATALL,
109               OVCACHEKEEP,
110               OVCACHEFREE
111           } OVCTLTYPE;
112
113           typedef enum {
114               OVNEWSGROUP,
115               OVARRIVED,
116               OVNOSORT
117           } OVSORTTYPE;
118
119           typedef enum {
120               OVADDCOMPLETED,
121               OVADDFAILED,
122               OVADDGROUPNOMATCH
123           } OVADDRESULT;
124
125           bool OVopen(int mode);
126
127           bool OVctl(OVCTLTYPE type, void *val);
128
129           bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);
130
131           bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
132
133           bool OVgroupdel(char *group);
134
135           OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived, time_t expires);
136
137           bool OVcancel(TOKEN token);
138
139           void *OVopensearch(char *group, int low, int high);
140
141           bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);
142
143           void OVclosesearch(void *handle);
144
145           bool OVgetartinfo(char *group, ARTNUM artnum, TOKEN *token);
146
147           bool OVexpiregroup(char *group, int *lo, struct history *h);
148
149           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
161           void OVclose(void);
162

DESCRIPTION

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
168       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
179       OV is a common utility routines for accessing newsgroups and overview
180       data independent of particular overview method.
181
182       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
192       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
196       The TokenToText function converts a token into a text string for
197       output.
198
199       The TextToToken function converts a text string into a token.
200
201       The SMsetup function configures some parameters for use by the storage
202       manager.  type is one of following:
203
204       "SM_RDWR"
205           Allow read/write open for storage files (default is false).
206
207       "SM_PREOPEN"
208           Open all storage files at startup time and keep them (default is
209           false).
210
211       value is the pointer which tells each type's value.  It returns true if
212       setup is successful, or false if not.
213
214       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
220       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
227       uwildmat(3) expression in storage.conf.  SMstore fails if SM_RDWR has
228       not been set to true with SMsetup.
229
230       The SMretrieve function retrieves an article specified with token.
231       amount is the one of following which specifies retrieving type:
232
233       "RETR_ALL"
234           Retrieve the whole article.
235
236       "RETR_HEAD"
237           Retrieve the headers of the article.
238
239       "RETR_BODY"
240           Retrieve the body of the article.
241
242       "RETR_STAT"
243           Just check to see if the article exists.
244
245       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
249       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
258       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
263       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
267       The SMprobe function checks the token on PROBETYPE.  type is one of
268       following:
269
270       "SELFEXPIRE"
271           Check to see if the method of the token has self expire
272           functionality.
273
274       "SMARTNGNUM"
275           Get the newsgroup name and the article number of the token.
276
277       "EXPENSIVESTAT"
278           Check to see whether checking the existence of an article is
279           expensive or not.
280
281       The SMprintfiles function shows file name or token usable by fastrm(8).
282
283       The SMflushcacheddata function flushes cached data on each storage
284       method.  type is one of following:
285
286       "SM_HEAD"
287           Flush cached header.
288
289       "SM_CANCELLEDART"
290           Flush the articles which should be cancelled.
291
292       "SM_ALL"
293           Flush all cached data.
294
295       The SMexplaintoken function returns a human-readable text string with a
296       clear, decoded form of the storage API token.
297
298       The SMshutdown function calls the shutdown for each configured storage
299       method and then frees any resources it has allocated for itself.
300
301       SMerrno and SMerrorstr indicate the reason of the last error concerning
302       storage manager.
303
304       OVopen calls the setup function for configured method which is
305       specified as ovmethod in inn.conf.  mode is constructed from following:
306
307       "OV_READ"
308           Allow read open for the overview method.
309
310       "OV_WRITE"
311           Allow write open for the overview method.
312
313       This function should be called prior to all other OV functions which
314       begin with "OV".
315
316       The OVctl function probes or sets some parameters for the overview
317       method.  type is one of following:
318
319       "OVGROUPBASEDEXPIRE"
320           Setup how group-based expiry is done.
321
322       "OVCUTOFFLOW"
323           Do not add overview data if the data is under the lowest article.
324
325       "OVSORT"
326           Probe which key is suitable for the overview method.
327
328       "OVSPACE"
329           Probe the overview space usage.
330
331       "OVSTATALL"
332           Stat all the articles when OVexpiregroup is called.
333
334       "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
338       "OVCACHEKEEP"
339           Setup whether the cache should be kept.
340
341       "OVCACHEFREE"
342           Free the cache.
343
344       The OVgroupstats function retrieves the specified newsgroup information
345       from the overview method.
346
347       The OVgroupadd function informs the overview method that the specified
348       newsgroup is being added.
349
350       The OVgroupdel function informs the overview method that the specified
351       newsgroup is being removed.
352
353       The OVadd function stores an overview data.
354
355       The OVcancel function requests the overview method delete overview data
356       specified with token.
357
358       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
366       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
376       The OVclosesearch function frees all resources which have been
377       allocated by OVopensearch.
378
379       The OVgetartinfo function retrieves the overview data and the token
380       specified with artnum.
381
382       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
387       The OVclose function frees all resources which are used by the overview
388       method.
389

HISTORY

391       Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
392       Converted to POD by Julien Elie.
393
394       $Id: libstorage.pod 9073 2010-05-31 19:00:23Z iulius $
395

SEE ALSO

397       expire(8), fastrm(8), inn.conf(5), storage.conf(5).
398
399
400
401INN 2.6.3                         2015-09-12                     libstorage(3)
Impressum