Provided by: inn2-dev_2.5.2-1_i386 bug

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).

                                                                 LIBSTORAGE(3)