chiark / gitweb /
option for no inotify; manpage fix
[innduct.git] / doc / man / libstorage.3
1 .\" $Revision: 6124 $
2 .TH LIBSTORAGE 3
3 .SH NAME
4 libstorage \- InterNetNews Storage API library routines
5 .SH SYNOPSIS
6 .nf
7 .ta \w'    unsigned long    'u
8
9 #include "storage.h"
10
11 .B "bool IsToken(const char *text);"
12
13 .B "char *TokenToText(const TOKEN token);"
14
15 .B "TOKEN TextToToken(const char *text);"
16
17 .B "bool SMsetup(SMSETUP type, void *value);"
18
19 .B "bool SMinit(void);"
20
21 .B "TOKEN SMstore(const ARTHANDLE article);"
22
23 .B "ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);"
24
25 .B "ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);"
26
27 .B "void SMfreearticle(ARTHANDLE *article);"
28
29 .B "bool SMcancel(TOKEN token);"
30
31 .B "bool SMprobe(PROBETYPE type, TOKEN *token, void *value);"
32
33 .B "void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)"
34
35 .B "bool SMflushcacheddata(FLUSHTYPE type);"
36
37 .B "void SMshutdown(void);"
38
39 .B "int SMerrno;"
40 .B "char *SMerrorstr;"
41
42 #include "ov.h"
43
44 .B "bool OVopen(int mode);"
45
46 .B "bool OVctl(OVCTLTYPE type, void *val);"
47
48 .B "bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);"
49
50 .B "bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);"
51
52 .B "bool OVgroupdel(char *group);"
53
54 .B "OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);"
55
56 .B "bool OVcancel(TOKEN token);"
57
58 .B "void *OVopensearch(char *group, int low, int high);"
59
60 .B "bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);"
61
62 .B "void OVclosesearch(void *handle);"
63
64 .B "bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);"
65
66 .B "bool OVexpiregroup(char *group, int *lo);"
67
68 .B "typedef struct _OVGE {"
69 .B "    bool        delayrm;"
70 .B "    bool        usepost;"
71 .B "    bool        quiet;"
72 .B "    bool        keep;"
73 .B "    bool        earliest;"
74 .B "    bool        ignoreselfexpire;"
75 .B "    char        *filename;"
76 .B "    time_t      now;"
77 .B "    float       timewarp;"
78 .B "} OVGE;"
79
80 .B "void OVclose(void);"
81
82 .fi
83 .SH DESCRIPTION
84 .I Libstorage
85 is a library of common utility (the storage manager) routines for accessing
86 Usenet articles and related data independent of particular storage method;
87 this is known as the storage API.
88 The storage manager's function is to isolate the applications from the
89 individual methods and make the policy decisions as to which storage method
90 should be called to store an article.
91 .PP
92 One of the core concepts in the storage API is that articles are not
93 manipulated using the message-id or article number, but rather a token that
94 uniquely identifies the article to the method that stored it.  This may seem
95 to be redundant since the message-id already is a unique identifier for the
96 article, however, since the storage method generates the token, it can
97 encode all the information it needs to locate the article in the token.
98 .PP
99 \&``OV'' is a common utility routines for accessing newsgroups and overview
100 data independent of particular overview method.
101 The ``OV'' function is to isolate the applications from the
102 individual methods.
103 .PP
104 All articles passed through the storage API are assumed to be in wire
105 format.  Wire format means ``\\CR\\LF'' at the end of lines, ``.'' at the
106 beginning of lines, and ``.\\CR\\LF'' at the end of article on NNTP stream
107 are not stripped.  This has a performance win when transferring articles.
108 For the ``tradspool'' method, wire format can be disabled.  This is just
109 for compatibility which is needed by some old tools written for
110 traditional spool.
111 .PP
112 .I IsToken
113 checks to see if the text is formatted as a text token string.
114 It returns true if formatted correctly or returns false if not.
115 .PP
116 .I TokenToText
117 converts token into text string for output.
118 .PP
119 .I TextToToken
120 converts text into token.
121 .PP
122 .I SMsetup
123 configures some parameters for use by storage manager.
124 .I Type
125 is one of following.
126 .sp 1
127 .in +0.5i
128 .nf
129 SM_RDWR allow read/write open for storage
130         files (default is false)
131 SM_PREOPEN      open all storage files at startup
132         time and keep them (default is false)
133 .fi
134 .in -0.5i
135 .sp 1
136 The
137 .I value
138 is the pointer which tells each type's value.
139 It returns true if setup is successful, or false if not.
140 .PP
141 .I SMinit
142 calls the setup function for all of the configured methods based on
143 .IR SMsetup .
144 This function should be called prior to all other storage API functions which
145 begin with ``SM'' except
146 .IR SMsetup .
147 It returns true if initialization is successful or returns false if not.
148 .I SMinit
149 returns true, unless all storage methods fail initialization.
150 .PP
151 .I SMstore
152 stores an article specified with
153 .IR article .
154 If
155 .I arrived
156 is specified,
157 .I SMstore
158 uses its value as article's arrival time; otherwise
159 .I SMstore
160 uses the current time for it.
161 .I SMstore
162 returns token type as
163 .IR type ,
164 or returns
165 .I TOKEN_EMPTY
166 if article is not stored because some error occurs or simply does not
167 match any
168 .IR uwildmat (3)
169 in
170 .IR storage.conf .
171 .I SMstore
172 fails if
173 .I SM_RDWR
174 has not been set to true with
175 .IR SMsetup .
176 .PP
177 .I SMretrieve
178 retrieves an article specified with
179 .IR token .
180 .I Amount
181 is the one of following which specifies retrieving type.
182 .sp 1
183 .in +0.5i
184 .nf
185 RETR_ALL        retrieve whole article
186 RETR_HEAD       retrieve headers of article
187 RETR_BODY       retrieve body of article
188 RETR_STAT       just check to see if article exists
189 .fi
190 .in -0.5i
191 .sp 1
192 .PP
193 The data area indicated by
194 .I ARTHANDLE
195 should not be modified.
196 .PP
197 .I SMnext
198 is similar in function to
199 .I SMretrieve
200 except that it is intended for traversing the method's article store
201 sequentially.
202 To start a query,
203 .I SMnext
204 should be called with a NULL pointer
205 .IR ARTHANDLE .
206 Then
207 .I SMnext
208 returns
209 .I ARTHANDLE
210 which should be used for the next query.
211 If a NULL pointer
212 .I ARTHANDLE
213 is returned, no articles are left to be queried.
214 If
215 .I data
216 of
217 .I ARTHANDLE
218 is NULL pointer or
219 .I len
220 of
221 .I ARTHANDLE
222 is 0, it indicates the article may be corrupted and should be cancelled by
223 .IR SMcancel .
224 The data area indicated by
225 .I ARTHANDLE
226 should not be modified.
227 .PP
228 .I SMfreearticle
229 frees all allocated memory used by
230 .I SMretrieve
231 and
232 .IR SMnext .
233 If
234 .I SMnext
235 will be called with previously returned
236 .IR ARTHANDLE ,
237 .I SMfreearticle
238 should not be called as
239 .I SMnext
240 frees allocated memory internally.
241 .PP
242 .I SMcancel
243 removes the article specified with
244 .IR token .
245 It returns true if cancellation is successful or returns false if not.
246 .I SMcancel
247 fails if
248 .I SM_RDWR
249 has not been set to true with
250 .IR SMsetup .
251 .PP
252 .I SMprobe
253 checks the token on
254 .IR PROBETYPE .
255 .I Type
256 is one of following.
257 .sp 1
258 .in +0.5i
259 .nf
260 SELFEXPIRE      checks to see if the method of the token
261         has self expire functionality
262 SMARTNGNUM      gets newsgroup name and article number
263         of the token.
264 .fi
265 .in -0.5i
266 .sp 1
267 .PP
268 .I SMprintfiles
269 shows file name or token usable by
270 .IR fastrm (8).
271 .PP
272 .I SMflushcacheddata
273 flushes cached data on each storage method.
274 .I Type
275 is one of following.
276 .sp 1
277 .in +0.5i
278 .nf
279 SM_HEAD flushes cached header
280 SM_CANCELEDART  flushes articles which should be canceled
281 SM_ALL  flushes all cached data
282 .fi
283 .in -0.5i
284 .sp 1
285 .PP
286 .I SMshutdown
287 calls the shutdown for each configured storage method and
288 then frees any resources it has allocated for itself.
289 .PP
290 .I SMerrno
291 and
292 .I SMerrorstr
293 indicate the reason of the last error concerning storage manager.
294 .PP
295 .I OVopen
296 calls the setup function for configured method which is specified as
297 \&``ovmethod'' in
298 .IR inn.conf .
299 .I Mode
300 is constructed from following.
301 .sp 1
302 .in +0.5i
303 .nf
304 OV_READ allow read open for overview
305         method
306 OV_WRITE        allow write open for overview
307         method
308 .fi
309 .in -0.5i
310 .sp 1
311 This function should be called prior to all other OV functions which
312 begin with ``OV''.
313 .PP
314 .I OVctl
315 probes or sets some parameters for overview method.
316 .I Type
317 is one of following.
318 .sp 1
319 .in +0.5i
320 .nf
321 OVGROUPBASEDEXPIRE      setup how group-based expiry is
322         done
323 OVCUTOFFLOW     do not add overview data, if the
324         data is under lowest article
325 OVSORT  probe which key is suitable for
326         overview method
327 OVSPACE probe overview space usage
328 OVSTATALL       stat all articles when
329         OVexpiregroup is called
330 .fi
331 .in -0.5i
332 .sp 1
333 .PP
334 .I OVgroupstats
335 retrieves specified newsgroup information from overview method.
336 .PP
337 .I OVgroupadd
338 informs overview method that specified newsgroup is being added.
339 .PP
340 .I OVgroupdel
341 informs overview method that specified newsgroup is being removed.
342 .PP
343 .I OVadd
344 stores an overview data.
345 .PP
346 .I OVcancel
347 requests the overview method delete overview data specified with token.
348 .PP
349 .I OVopensearch
350 requests the overview method prepare overview data retrieval.
351 The request range is determined by
352 .I low
353 and
354 .IR high .
355 .PP
356 .I OVsearch
357 retrieves information; article number, overview data, or arrival time.
358 .I OVsearch
359 should be called with NULL handle when it is the first time;
360 subsequent
361 .I OVsearch
362 calls should use the handle returned by the previous call to
363 .IR OVsearch .
364 .I OVsearch
365 returns true, unless it reaches high which is specified by
366 .IR OVopensearch .
367 Retrieved overview data are sorted by article number, and
368 .I len
369 is ``0'' if there is no overview data for article.  Note that the
370 retrieved data is not neccessarily null-terminated; you should only rely
371 on
372 .I len
373 octets of overview data being present.
374 .PP
375 .I OVclosesearch
376 frees all resources which have been allocated by
377 .IR OVopensearch .
378 .PP
379 .I OVgetartinfo
380 retrieves overview data and token specified with
381 .IR artnum .
382 .PP
383 .I OVexpiregroup
384 expires overview data for the newsgroup.
385 .I OVexpiregroup
386 checks the existense of the article and purges overview data if the
387 article no longer exists.
388 If ``groupbaseexpiry'' in
389 .I inn.conf
390 is true,
391 .I OVexpiregroup
392 also expires articles.
393 .PP
394 .I OVclose
395 frees all resources which are used by the overview method.
396 .SH HISTORY
397 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
398 .de R$
399 This is revision \\$3, dated \\$4.
400 ..
401 .R$ $Id: libstorage.3 6124 2003-01-14 06:03:29Z rra $
402 .SH "SEE ALSO"
403 expire(8),
404 inn.conf(5),
405 storage.conf(5).