1LIBSTORAGE(3) Library Functions Manual LIBSTORAGE(3)
2
6 libstorage - InterNetNews Storage API library routines
7
9 #include "storage.h"
10 bool IsToken(const char *text);
12 char *TokenToText(const TOKEN token);
14 TOKEN TextToToken(const char *text);
16 bool SMsetup(SMSETUP type, void *value);
18 bool SMinit(void);
20 TOKEN SMstore(const ARTHANDLE article);
22 ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);
24 ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);
26 void SMfreearticle(ARTHANDLE *article);
28 bool SMcancel(TOKEN token);
30 bool SMprobe(PROBETYPE type, TOKEN *token, void *value);
32 void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)
34 bool SMflushcacheddata(FLUSHTYPE type);
36 void SMshutdown(void);
38 int SMerrno;
40 char *SMerrorstr;
41 #include "ov.h"
43 bool OVopen(int mode);
45 bool OVctl(OVCTLTYPE type, void *val);
47 bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);
49 bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
51 bool OVgroupdel(char *group);
53 OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);
55 bool OVcancel(TOKEN token);
57 void *OVopensearch(char *group, int low, int high);
59 bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);
61 void OVclosesearch(void *handle);
63 bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);
65 bool OVexpiregroup(char *group, int *lo);
67 typedef struct _OVGE {
69 bool delayrm;
70 bool usepost;
71 bool quiet;
72 bool keep;
73 bool earliest;
74 bool ignoreselfexpire;
75 char *filename;
76 time_t now;
77 float timewarp;
78 } OVGE;
79 void OVclose(void);
81
84 Libstorage is a library of common utility (the storage manager) rou‐
85 tines for accessing Usenet articles and related data independent of
86 particular storage method; this is known as the storage API. The stor‐
87 age manager's function is to isolate the applications from the individ‐
88 ual methods and make the policy decisions as to which storage method
89 should be called to store an article.
90 One of the core concepts in the storage API is that articles are not
92 manipulated using the message-id or article number, but rather a token
93 that uniquely identifies the article to the method that stored it.
94 This may seem to be redundant since the message-id already is a unique
95 identifier for the article, however, since the storage method generates
96 the token, it can encode all the information it needs to locate the
97 article in the token.
98 ``OV'' is a common utility routines for accessing newsgroups and over‐
100 view data independent of particular overview method. The ``OV'' func‐
101 tion is to isolate the applications from the individual methods.
102 All articles passed through the storage API are assumed to be in wire
104 format. Wire format means ``\CR\LF'' at the end of lines, ``.'' at the
105 beginning of lines, and ``.\CR\LF'' at the end of article on NNTP
106 stream are not stripped. This has a performance win when transferring
107 articles. For the ``tradspool'' method, wire format can be disabled.
108 This is just for compatibility which is needed by some old tools writ‐
109 ten for traditional spool.
110 IsToken checks to see if the text is formatted as a text token string.
112 It returns true if formatted correctly or returns false if not.
113 TokenToText converts token into text string for output.
115 TextToToken converts text into token.
117 SMsetup configures some parameters for use by storage manager. Type is
119 one of following.
120 SM_RDWR allow read/write open for storage
122 files (default is false)
123 SM_PREOPEN open all storage files at startup
124 time and keep them (default is false)
125 The value is the pointer which tells each type's value. It returns
127 true if setup is successful, or false if not.
128 SMinit calls the setup function for all of the configured methods based
130 on SMsetup. This function should be called prior to all other storage
131 API functions which begin with ``SM'' except SMsetup. It returns true
132 if initialization is successful or returns false if not. SMinit
133 returns true, unless all storage methods fail initialization.
134 SMstore stores an article specified with article. If arrived is speci‐
136 fied, SMstore uses its value as article's arrival time; otherwise
137 SMstore uses the current time for it. SMstore returns token type as
138 type, or returns TOKEN_EMPTY if article is not stored because some
139 error occurs or simply does not match any uwildmat(3) in storage.conf.
140 SMstore fails if SM_RDWR has not been set to true with SMsetup.
141 SMretrieve retrieves an article specified with token. Amount is the
143 one of following which specifies retrieving type.
144 RETR_ALL retrieve whole article
146 RETR_HEAD retrieve headers of article
147 RETR_BODY retrieve body of article
148 RETR_STAT just check to see if article exists
149 The data area indicated by ARTHANDLE should not be modified.
152 SMnext is similar in function to SMretrieve except that it is intended
154 for traversing the method's article store sequentially. To start a
155 query, SMnext should be called with a NULL pointer ARTHANDLE. Then
156 SMnext returns ARTHANDLE which should be used for the next query. If a
157 NULL pointer ARTHANDLE is returned, no articles are left to be queried.
158 If data of ARTHANDLE is NULL pointer or len of ARTHANDLE is 0, it indi‐
159 cates the article may be corrupted and should be cancelled by SMcancel.
160 The data area indicated by ARTHANDLE should not be modified.
161 SMfreearticle frees all allocated memory used by SMretrieve and SMnext.
163 If SMnext will be called with previously returned ARTHANDLE,
164 SMfreearticle should not be called as SMnext frees allocated memory
165 internally.
166 SMcancel removes the article specified with token. It returns true if
168 cancellation is successful or returns false if not. SMcancel fails if
169 SM_RDWR has not been set to true with SMsetup.
170 SMprobe checks the token on PROBETYPE. Type is one of following.
172 SELFEXPIRE checks to see if the method of the token
174 has self expire functionality
175 SMARTNGNUM gets newsgroup name and article number
176 of the token.
177 SMprintfiles shows file name or token usable by fastrm(8).
180 SMflushcacheddata flushes cached data on each storage method. Type is
182 one of following.
183 SM_HEAD flushes cached header
185 SM_CANCELEDART flushes articles which should be canceled
186 SM_ALL flushes all cached data
187 SMshutdown calls the shutdown for each configured storage method and
190 then frees any resources it has allocated for itself.
191 SMerrno and SMerrorstr indicate the reason of the last error concerning
193 storage manager.
194 OVopen calls the setup function for configured method which is speci‐
196 fied as ``ovmethod'' in inn.conf. Mode is constructed from following.
197 OV_READ allow read open for overview
199 method
200 OV_WRITE allow write open for overview
201 method
202 This function should be called prior to all other OV functions which
204 begin with ``OV''.
205 OVctl probes or sets some parameters for overview method. Type is one
207 of following.
208 OVGROUPBASEDEXPIRE setup how group-based expiry is
210 done
211 OVCUTOFFLOW do not add overview data, if the
212 data is under lowest article
213 OVSORT probe which key is suitable for
214 overview method
215 OVSPACE probe overview space usage
216 OVSTATALL stat all articles when
217 OVexpiregroup is called
218 OVgroupstats retrieves specified newsgroup information from overview
221 method.
222 OVgroupadd informs overview method that specified newsgroup is being
224 added.
225 OVgroupdel informs overview method that specified newsgroup is being
227 removed.
228 OVadd stores an overview data.
230 OVcancel requests the overview method delete overview data specified
232 with token.
233 OVopensearch requests the overview method prepare overview data
235 retrieval. The request range is determined by low and high.
236 OVsearch retrieves information; article number, overview data, or
238 arrival time. OVsearch should be called with NULL handle when it is
239 the first time; subsequent OVsearch calls should use the handle
240 returned by the previous call to OVsearch. OVsearch returns true,
241 unless it reaches high which is specified by OVopensearch. Retrieved
242 overview data are sorted by article number, and len is ``0'' if there
243 is no overview data for article. Note that the retrieved data is not
244 neccessarily null-terminated; you should only rely on len octets of
245 overview data being present.
246 OVclosesearch frees all resources which have been allocated by
248 OVopensearch.
249 OVgetartinfo retrieves overview data and token specified with artnum.
251 OVexpiregroup expires overview data for the newsgroup. OVexpiregroup
253 checks the existense of the article and purges overview data if the
254 article no longer exists. If ``groupbaseexpiry'' in inn.conf is true,
255 OVexpiregroup also expires articles.
256 OVclose frees all resources which are used by the overview method.
258
260 Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. This
261 is revision 6124, dated 2003-01-14.
262
264 expire(8), inn.conf(5), storage.conf(5).
265 LIBSTORAGE(3)