+++ /dev/null
-.\" $Revision: 6124 $
-.TH LIBSTORAGE 3
-.SH NAME
-libstorage \- InterNetNews Storage API library routines
-.SH SYNOPSIS
-.nf
-.ta \w' unsigned long 'u
-
-#include "storage.h"
-
-.B "bool IsToken(const char *text);"
-
-.B "char *TokenToText(const TOKEN token);"
-
-.B "TOKEN TextToToken(const char *text);"
-
-.B "bool SMsetup(SMSETUP type, void *value);"
-
-.B "bool SMinit(void);"
-
-.B "TOKEN SMstore(const ARTHANDLE article);"
-
-.B "ARTHANDLE *SMretrieve(const TOKEN token, const RETRTYPE amount);"
-
-.B "ARTHANDLE *SMnext(const ARTHANDLE *article, const RETRTYPE amount);"
-
-.B "void SMfreearticle(ARTHANDLE *article);"
-
-.B "bool SMcancel(TOKEN token);"
-
-.B "bool SMprobe(PROBETYPE type, TOKEN *token, void *value);"
-
-.B "void SMprintfiles(FILE *file, TOKEN token, char **xref, int ngroups)"
-
-.B "bool SMflushcacheddata(FLUSHTYPE type);"
-
-.B "void SMshutdown(void);"
-
-.B "int SMerrno;"
-.B "char *SMerrorstr;"
-
-#include "ov.h"
-
-.B "bool OVopen(int mode);"
-
-.B "bool OVctl(OVCTLTYPE type, void *val);"
-
-.B "bool OVgroupstats(char *group, int *lo, int *hi, int *count, int *flag);"
-
-.B "bool OVgroupadd(char *group, ARTNUM lo, ARTNUM hi, char *flag);"
-
-.B "bool OVgroupdel(char *group);"
-
-.B "OVADDRESULT OVadd(TOKEN token, char *data, int len, time_t arrived);"
-
-.B "bool OVcancel(TOKEN token);"
-
-.B "void *OVopensearch(char *group, int low, int high);"
-
-.B "bool OVsearch(void *handle, ARTNUM *artnum, char **data, int *len, TOKEN *token, time_t *arrived);"
-
-.B "void OVclosesearch(void *handle);"
-
-.B "bool OVgetartinfo(char *group, ARTNUM artnum, char **data, int *len, TOKEN *token);"
-
-.B "bool OVexpiregroup(char *group, int *lo);"
-
-.B "typedef struct _OVGE {"
-.B " bool delayrm;"
-.B " bool usepost;"
-.B " bool quiet;"
-.B " bool keep;"
-.B " bool earliest;"
-.B " bool ignoreselfexpire;"
-.B " char *filename;"
-.B " time_t now;"
-.B " float timewarp;"
-.B "} OVGE;"
-
-.B "void OVclose(void);"
-
-.fi
-.SH DESCRIPTION
-.I 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.
-.PP
-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.
-.PP
-\&``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.
-.PP
-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.
-.PP
-.I 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.
-.PP
-.I TokenToText
-converts token into text string for output.
-.PP
-.I TextToToken
-converts text into token.
-.PP
-.I SMsetup
-configures some parameters for use by storage manager.
-.I Type
-is one of following.
-.sp 1
-.in +0.5i
-.nf
-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)
-.fi
-.in -0.5i
-.sp 1
-The
-.I value
-is the pointer which tells each type's value.
-It returns true if setup is successful, or false if not.
-.PP
-.I SMinit
-calls the setup function for all of the configured methods based on
-.IR SMsetup .
-This function should be called prior to all other storage API functions which
-begin with ``SM'' except
-.IR SMsetup .
-It returns true if initialization is successful or returns false if not.
-.I SMinit
-returns true, unless all storage methods fail initialization.
-.PP
-.I SMstore
-stores an article specified with
-.IR article .
-If
-.I arrived
-is specified,
-.I SMstore
-uses its value as article's arrival time; otherwise
-.I SMstore
-uses the current time for it.
-.I SMstore
-returns token type as
-.IR type ,
-or returns
-.I TOKEN_EMPTY
-if article is not stored because some error occurs or simply does not
-match any
-.IR uwildmat (3)
-in
-.IR storage.conf .
-.I SMstore
-fails if
-.I SM_RDWR
-has not been set to true with
-.IR SMsetup .
-.PP
-.I SMretrieve
-retrieves an article specified with
-.IR token .
-.I Amount
-is the one of following which specifies retrieving type.
-.sp 1
-.in +0.5i
-.nf
-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
-.fi
-.in -0.5i
-.sp 1
-.PP
-The data area indicated by
-.I ARTHANDLE
-should not be modified.
-.PP
-.I SMnext
-is similar in function to
-.I SMretrieve
-except that it is intended for traversing the method's article store
-sequentially.
-To start a query,
-.I SMnext
-should be called with a NULL pointer
-.IR ARTHANDLE .
-Then
-.I SMnext
-returns
-.I ARTHANDLE
-which should be used for the next query.
-If a NULL pointer
-.I ARTHANDLE
-is returned, no articles are left to be queried.
-If
-.I data
-of
-.I ARTHANDLE
-is NULL pointer or
-.I len
-of
-.I ARTHANDLE
-is 0, it indicates the article may be corrupted and should be cancelled by
-.IR SMcancel .
-The data area indicated by
-.I ARTHANDLE
-should not be modified.
-.PP
-.I SMfreearticle
-frees all allocated memory used by
-.I SMretrieve
-and
-.IR SMnext .
-If
-.I SMnext
-will be called with previously returned
-.IR ARTHANDLE ,
-.I SMfreearticle
-should not be called as
-.I SMnext
-frees allocated memory internally.
-.PP
-.I SMcancel
-removes the article specified with
-.IR token .
-It returns true if cancellation is successful or returns false if not.
-.I SMcancel
-fails if
-.I SM_RDWR
-has not been set to true with
-.IR SMsetup .
-.PP
-.I SMprobe
-checks the token on
-.IR PROBETYPE .
-.I Type
-is one of following.
-.sp 1
-.in +0.5i
-.nf
-SELFEXPIRE checks to see if the method of the token
- has self expire functionality
-SMARTNGNUM gets newsgroup name and article number
- of the token.
-.fi
-.in -0.5i
-.sp 1
-.PP
-.I SMprintfiles
-shows file name or token usable by
-.IR fastrm (8).
-.PP
-.I SMflushcacheddata
-flushes cached data on each storage method.
-.I Type
-is one of following.
-.sp 1
-.in +0.5i
-.nf
-SM_HEAD flushes cached header
-SM_CANCELEDART flushes articles which should be canceled
-SM_ALL flushes all cached data
-.fi
-.in -0.5i
-.sp 1
-.PP
-.I SMshutdown
-calls the shutdown for each configured storage method and
-then frees any resources it has allocated for itself.
-.PP
-.I SMerrno
-and
-.I SMerrorstr
-indicate the reason of the last error concerning storage manager.
-.PP
-.I OVopen
-calls the setup function for configured method which is specified as
-\&``ovmethod'' in
-.IR inn.conf .
-.I Mode
-is constructed from following.
-.sp 1
-.in +0.5i
-.nf
-OV_READ allow read open for overview
- method
-OV_WRITE allow write open for overview
- method
-.fi
-.in -0.5i
-.sp 1
-This function should be called prior to all other OV functions which
-begin with ``OV''.
-.PP
-.I OVctl
-probes or sets some parameters for overview method.
-.I Type
-is one of following.
-.sp 1
-.in +0.5i
-.nf
-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
-.fi
-.in -0.5i
-.sp 1
-.PP
-.I OVgroupstats
-retrieves specified newsgroup information from overview method.
-.PP
-.I OVgroupadd
-informs overview method that specified newsgroup is being added.
-.PP
-.I OVgroupdel
-informs overview method that specified newsgroup is being removed.
-.PP
-.I OVadd
-stores an overview data.
-.PP
-.I OVcancel
-requests the overview method delete overview data specified with token.
-.PP
-.I OVopensearch
-requests the overview method prepare overview data retrieval.
-The request range is determined by
-.I low
-and
-.IR high .
-.PP
-.I OVsearch
-retrieves information; article number, overview data, or arrival time.
-.I OVsearch
-should be called with NULL handle when it is the first time;
-subsequent
-.I OVsearch
-calls should use the handle returned by the previous call to
-.IR OVsearch .
-.I OVsearch
-returns true, unless it reaches high which is specified by
-.IR OVopensearch .
-Retrieved overview data are sorted by article number, and
-.I 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
-.I len
-octets of overview data being present.
-.PP
-.I OVclosesearch
-frees all resources which have been allocated by
-.IR OVopensearch .
-.PP
-.I OVgetartinfo
-retrieves overview data and token specified with
-.IR artnum .
-.PP
-.I OVexpiregroup
-expires overview data for the newsgroup.
-.I OVexpiregroup
-checks the existense of the article and purges overview data if the
-article no longer exists.
-If ``groupbaseexpiry'' in
-.I inn.conf
-is true,
-.I OVexpiregroup
-also expires articles.
-.PP
-.I OVclose
-frees all resources which are used by the overview method.
-.SH HISTORY
-Written by Katsuhiro Kondou <kondou@nec.co.jp> for InterNetNews.
-.de R$
-This is revision \\$3, dated \\$4.
-..
-.R$ $Id: libstorage.3 6124 2003-01-14 06:03:29Z rra $
-.SH "SEE ALSO"
-expire(8),
-inn.conf(5),
-storage.conf(5).
~ian / innduct.git / blobdiff