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