Linux Certif

Toute la documentation sur la certification Linux LPI

libstorage

NAME

libstorage - InterNetNews Storage API library routines

SYNOPSIS

 
 
 #include "inn/storage.h"
 
 bool IsToken(const char *text);
 
 char *TokenToText(const TOKEN token);
 
 TOKEN TextToToken(const char *text);
 
 bool SMsetup(SMSETUP type, void *value);
 
 bool SMinit(void);
 
 TOKEN SMstore(const ARTHANDLE article);
 
 ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);
 
 ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);
 
 void SMfreearticle(ARTHANDLE *article);
 
 bool SMcancel(TOKEN token);
 
 bool SMprobe(PROBETYPE type, TOKEN *token, void *value);
 
 void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)
 
 bool SMflushcacheddata(FLUSHTYPE type);
 
 void SMshutdown(void);
 
 int SMerrno;
 char *SMerrorstr;
 
 #include "inn/ov.h"
 
 bool OVopen(int mode);
 
 bool OVctl(OVCTLTYPE type, void *val);
 
 bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);
 
 bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);
 
 bool OVgroupdel(char *group);
 
 OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);
 
 bool OVcancel(TOKEN token);
 
 void *OVopensearch(char *group, int low, int high);
 
 bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);
 
 void OVclosesearch(void *handle);
 
 bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);
 
 bool OVexpiregroup(char *group, int *lo);
 
 typedef struct _OVGE {
     bool        delayrm;
     bool        usepost;
     bool        quiet;
     bool        keep;
     bool        earliest;
     bool        ignoreselfexpire;
     char        *filename;
     time_t      now;
     float       timewarp;
 } OVGE;
 
 void OVclose(void);
 
 

DESCRIPTION

Libstorage is a library of common utility (the storage manager) routines for accessing Usenet articles and related data independent of particular storage method; this is known as the storage API. The storage manager's function is to isolate the applications from the individual methods and make the policy decisions as to which storage method should be called to store an article.

One of the core concepts in the storage API is that articles are not manipulated using the message-id or article number, but rather a token that uniquely identifies the article to the method that stored it. This may seem to be redundant since the message-id already is a unique identifier for the article, however, since the storage method generates the token, it can encode all the information it needs to locate the article in the token.

``OV'' is a common utility routines for accessing newsgroups and overview data independent of particular overview method. The ``OV'' function is to isolate the applications from the individual methods.

All articles passed through the storage API are assumed to be in wire format. Wire format means ``\CR\LF'' at the end of lines, ``.'' at the beginning of lines, and ``.\CR\LF'' at the end of article on NNTP stream are not stripped. This has a performance win when transferring articles. For the ``tradspool'' method, wire format can be disabled. This is just for compatibility which is needed by some old tools written for traditional spool.

IsToken checks to see if the text is formatted as a text token string. It returns true if formatted correctly or returns false if not.

TokenToText converts token into text string for output.

TextToToken converts text into token.

SMsetup configures some parameters for use by storage manager. Type is one of following.

 SM_RDWR              allow read/write open for storage
                      files (default is false)
 SM_PREOPEN           open all storage files at startup
                      time and keep them (default is false)
 

The value is the pointer which tells each type's value. It returns true if setup is successful, or false if not.

SMinit calls the setup function for all of the configured methods based on SMsetup. This function should be called prior to all other storage API functions which begin with ``SM'' except SMsetup. It returns true if initialization is successful or returns false if not. SMinit returns true, unless all storage methods fail initialization.

SMstore stores an article specified with article. If arrived is specified, SMstore uses its value as article's arrival time; otherwise SMstore uses the current time for it. SMstore returns token type as type, or returns TOKEN_EMPTY if article is not stored because some error occurs or simply does not match any uwildmat(3) in storage.conf. SMstore fails if SM_RDWR has not been set to true with SMsetup.

SMretrieve retrieves an article specified with token. Amount is the one of following which specifies retrieving type.

 RETR_ALL             retrieve whole article
 RETR_HEAD            retrieve headers of article
 RETR_BODY            retrieve body of article
 RETR_STAT            just check to see if article exists
 

The data area indicated by ARTHANDLE should not be modified.

SMnext is similar in function to SMretrieve except that it is intended for traversing the method's article store sequentially. To start a query, SMnext should be called with a NULL pointer ARTHANDLE. Then SMnext returns ARTHANDLE which should be used for the next query. If a NULL pointer ARTHANDLE is returned, no articles are left to be queried. If data of ARTHANDLE is NULL pointer or len of ARTHANDLE is 0, it indicates the article may be corrupted and should be cancelled by SMcancel. The data area indicated by ARTHANDLE should not be modified.

SMfreearticle frees all allocated memory used by SMretrieve and SMnext. If SMnext will be called with previously returned ARTHANDLE, SMfreearticle should not be called as SMnext frees allocated memory internally.

SMcancel removes the article specified with token. It returns true if cancellation is successful or returns false if not. SMcancel fails if SM_RDWR has not been set to true with SMsetup.

SMprobe checks the token on PROBETYPE. Type is one of following.

 SELFEXPIRE           checks to see if the method of the token
                      has self expire functionality
 SMARTNGNUM           gets newsgroup name and article number
                      of the token.
 

SMprintfiles shows file name or token usable by fastrm(8).

SMflushcacheddata flushes cached data on each storage method. Type is one of following.

 SM_HEAD              flushes cached header
 SM_CANCELLEDART      flushes articles which should be cancelled
 SM_ALL               flushes all cached data
 

SMshutdown calls the shutdown for each configured storage method and then frees any resources it has allocated for itself.

SMerrno and SMerrorstr indicate the reason of the last error concerning storage manager.

OVopen calls the setup function for configured method which is specified as ``ovmethod'' in inn.conf. Mode is constructed from following.

 OV_READ              allow read open for overview
                      method
 OV_WRITE             allow write open for overview
                      method
 

This function should be called prior to all other OV functions which begin with ``OV''.

OVctl probes or sets some parameters for overview method. Type is one of following.

 OVGROUPBASEDEXPIRE   setup how group-based expiry is
                      done
 OVCUTOFFLOW          do not add overview data, if the
                      data is under lowest article
 OVSORT               probe which key is suitable for
                      overview method
 OVSPACE              probe overview space usage
 OVSTATALL            stat all articles when
                      OVexpiregroup is called
 OVSTATICSEARCH       if results of OVsearch are stored
                      in a static buffer and must be copied
                      before the next call to OVsearch
 

OVgroupstats retrieves specified newsgroup information from overview method.

OVgroupadd informs overview method that specified newsgroup is being added.

OVgroupdel informs overview method that specified newsgroup is being removed.

OVadd stores an overview data.

OVcancel requests the overview method delete overview data specified with token.

OVopensearch requests the overview method prepare overview data retrieval. The request range is determined by low and high. The setting of OVSTATICSEARCH determines how search result data must be handled. (Note that with some storage methods, each call to OVopensearch may cause internal storage to be remapped. Therefore multiple simultaneous searches may require data to be copied in between OVsearch calls even if OVSTATICSEARCH is false.)

OVsearch retrieves information; article number, overview data, or arrival time. OVsearch should be called with NULL handle when it is the first time; subsequent OVsearch calls should use the handle returned by the previous call to OVsearch. OVsearch returns true, unless it reaches high which is specified by OVopensearch. Retrieved overview data are sorted by article number, and len is ``0'' if there is no overview data for article. Note that the retrieved data is not neccessarily null-terminated; you should only rely on len octets of overview data being present.

OVclosesearch frees all resources which have been allocated by OVopensearch.

OVgetartinfo retrieves overview data and token specified with artnum.

OVexpiregroup expires overview data for the newsgroup. OVexpiregroup checks the existense of the article and purges overview data if the article no longer exists. If ``groupbaseexpiry'' in inn.conf is true, OVexpiregroup also expires articles.

OVclose frees all resources which are used by the overview method.

HISTORY

Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews. This is revision 8451, dated 2009-05-07.

SEE ALSO

expire(8), inn.conf(5), storage.conf(5).