LIBSTORAGE(3)LIBSTORAGE(3)NAMElibstorage - InterNetNews Storage API library routines
SYNOPSIS
#include "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 SMshutdown(void);
int SMerrno;
char *SMerrorstr;
BOOL OVERsetup(OVERSETUP type, void *value);
BOOL OVERinit(void);
BOOL OVERnewinit(void);
BOOL OVERreinit(void);
BOOL OVERreplace(void);
int OVERgetnum(void);
BOOL OVERstore(TOKEN *token, char *overdata, int overlen);
char *OVERretrieve(TOKEN *token, int *overlen);
BOOL OVERcancel(TOKEN *token);
void OVERshutdown(void);
1
LIBSTORAGE(3)LIBSTORAGE(3)DESCRIPTION
Libstorage is a library of common utility (the storage
manager) routines for accessing Usenet articles and
related data independent of particular storage method, and
this is called storage api. The storage manager's func-
tion 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 arti-
cles 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 identi-
fier 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.
Unified overview is a new method to access overview
database. With this method, all overview database are
stored in a pre-configured overview database files. It is
different from traditional overview database storage with
which overview database is stored in each newsgroup direc-
tory. Instead, overview index which indicates article
number and Message-ID hash is stored in each newsgroup
directory. If storage api is used, you should set up uni-
fied overview which is configured by overview.ctl(5) if
the server runs nnrpd(8).
All articles passed through storage api are assumed to be
wire formatted. Wire formatted means that ``\CR\LF'' at
the end of lines, ``.'' at the beginnig of lines and
``.\CR\LF'' at the end of article on nntp stream are not
stripped. This has performance win when transferring
articles.
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 token string.
TextToToken converts text into token.
SMsetup configures some parameters for use by storage man-
ager. 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 returns FALSE if
2
LIBSTORAGE(3)LIBSTORAGE(3)
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 use its value as article's
arrival time or SMstore use current time for it. SMstore
returns token type as type, or returns TOKEN_EMPTY if
article is not stored whichever error occures or simply
does not match wildmat(3) in storage.conf(5). SMstore
fails if SM_RDWR is not 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 modi-
fied.
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
NULL pointer ARTHANDLE is returned, no article is left to
be queried. If data of ARTHANDLE is NULL pointer or len
of ARTHANDLE is 0, it indicates the article may be cor-
rupted and should be cancelled by SMcancel. The data area
indicated by ARTHANDLE should not be modified.
SMfreearticle frees all allocated memory used by SMre-
trieve and SMnext. If SMnext will be called with previ-
ously returned ARTHANDLE, SMfreearticle should not be
called as SMnext frees allocated memory in itself.
SMcancel removes an article specified with token. It
returns TRUE if cancellation is successful or returns
FALSE if not. SMcancel fails if SM_RDWR is not set to
true with SMsetup.
SMprobe checks the token on PROBETYPE. Currently, only
SELFEXPIRE is supported and this can be used to see if the
method of the token has self expire functionality.
3
LIBSTORAGE(3)LIBSTORAGE(3)
SMshutdown calls the shutdown for each configured storage
method and then free any resources it has allocated for
itself.
SMerrno and SMerrorstr indicates the reason of the last
error concerning storage manager.
OVERsetup configures some parameters for use by OVERinit.
Type is one of following.
OVER_CTL specify overview.ctl file name
OVER_DIR specify unified overview directory
OVER_NEWDIR specify new unified overview directory
OVER_MODE specify unified overview open mode
OVER_NEWMODE specify new unified overview open mode
OVER_MMAP mmap unified overview
The value is the pointer which tells each type's value.
Open mode is equivalent value to fopen(3)'s mode. It
returns TRUE if setup is successful or returns FALSE if
not.
OVERinit calls the setup function and opens configured
overview file based on OVERsetup. This function should be
called prior to all other unified overview functions which
begin with ``OVER'' except OVERsetup. It returns TRUE if
initialization is successful or returns FALSE if not.
OVERnewinit calls the setup function and opens configured
new overview file based on OVERsetup. If OVERnewinit is
called, then OVERstore stores overview database into new
overview file not into current overview file which is
opened by OVERinit. This function is intended to be used
unified overview expiry together with OVERreinit and OVER-
replace. It returns TRUE if initialization is successful
or returns FALSE if not.
OVERreinit reinitialize current overview file. This is
intended to read rest of overview file when expire(8)
reaches end of history and pauses innd(8). It returns
TRUE if re initialization is successful or returns FALSE
if not.
OVERreplace replaces current overview file with new one.
It returns TRUE if replace is successful or returns FALSE
if not.
OVERgetnum tells the number of file descriptor which is
opened as unified overview file. It just tells current
overview file, and does not include new overview file. It
returns the number if initialization is done or returns
``-1'' if not.
OVERstore stores overview data into configured unified
4
LIBSTORAGE(3)LIBSTORAGE(3)
overview file. Index and offset is written into token.
It returns TRUE if the store is successful or returns
FALSE if not.
OVERretrieve retrieves overview data which is indicated by
token. It returns the pointer if the retrieval is suc-
cessful and overlen is set or returns NULL if not.
OVERcancel marks token's overview data is canceled. It
returns TRUE if cancellation is successful or returns
FALSE if not.
OVERshutdown calls the shutdown for each configured uni-
fied overview then free any resources it has allocated for
itself.
HISTORY
Written by Katsuhiro Kondou <kondou@nec.co.jp> for Inter-
NetNews. This is revision 1.1.2.1, dated 1999/06/12.
SEE ALSOexpire(8), inn.conf(5), overview.ctl(5), storage.conf(5).
5