.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.43) .\" .\" Standard preamble: .\" ======================================================================== .de Sp \" Vertical space (when we can't use .PP) .if t .sp .5v .if n .sp .. .de Vb \" Begin verbatim text .ft CW .nf .ne \\$1 .. .de Ve \" End verbatim text .ft R .fi .. .\" Set up some character translations and predefined strings. \*(-- will .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left .\" double quote, and \*(R" will give a right double quote. \*(C+ will .\" give a nicer C++. Capital omega is used to do unbreakable dashes and .\" therefore won't be available. \*(C` and \*(C' expand to `' in nroff, .\" nothing in troff, for use with C<>. .tr \(*W- .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' .ie n \{\ . ds -- \(*W- . ds PI pi . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch . ds L" "" . ds R" "" . ds C` "" . ds C' "" 'br\} .el\{\ . ds -- \|\(em\| . ds PI \(*p . ds L" `` . ds R" '' . ds C` . ds C' 'br\} .\" .\" Escape single quotes in literal strings from groff's Unicode transform. .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" .\" If the F register is >0, we'll generate index entries on stderr for .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index .\" entries marked with X<> in POD. Of course, you'll have to process the .\" output yourself in some meaningful fashion. .\" .\" Avoid warning from groff about undefined register 'F'. .de IX .. .nr rF 0 .if \n(.g .if rF .nr rF 1 .if (\n(rF:(\n(.g==0)) \{\ . if \nF \{\ . de IX . tm Index:\\$1\t\\n%\t"\\$2" .. . if !\nF==2 \{\ . nr % 0 . nr F 2 . \} . \} .\} .rr rF .\" .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). .\" Fear. Run. Save yourself. No user-serviceable parts. . \" fudge factors for nroff and troff .if n \{\ . ds #H 0 . ds #V .8m . ds #F .3m . ds #[ \f1 . ds #] \fP .\} .if t \{\ . ds #H ((1u-(\\\\n(.fu%2u))*.13m) . ds #V .6m . ds #F 0 . ds #[ \& . ds #] \& .\} . \" simple accents for nroff and troff .if n \{\ . ds ' \& . ds ` \& . ds ^ \& . ds , \& . ds ~ ~ . ds / .\} .if t \{\ . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' .\} . \" troff and (daisy-wheel) nroff accents .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' .ds 8 \h'\*(#H'\(*b\h'-\*(#H' .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] .ds ae a\h'-(\w'a'u*4/10)'e .ds Ae A\h'-(\w'A'u*4/10)'E . \" corrections for vroff .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' . \" for low resolution devices (crt and lpr) .if \n(.H>23 .if \n(.V>19 \ \{\ . ds : e . ds 8 ss . ds o a . ds d- d\h'-1'\(ga . ds D- D\h'-1'\(hy . ds th \o'bp' . ds Th \o'LP' . ds ae ae . ds Ae AE .\} .rm #[ #] #H #V #F C .\" ======================================================================== .\" .IX Title "libstorage 3" .TH libstorage 3 "2022-10-20" "INN 2.6.5" "InterNetNews Documentation" .\" For nroff, turn off justification. Always turn off hyphenation; it makes .\" way too many mistakes in technical documents. .if n .ad l .nh .SH "NAME" libstorage \- routines for managing INN storage .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include \& \& typedef enum { \& RETR_ALL, \& RETR_HEAD, \& RETR_BODY, \& RETR_STAT \& } RETRTYPE; \& \& typedef enum { \& SM_RDWR, \& SM_PREOPEN \& } SMSETUP; \& \& typedef unsigned char STORAGECLASS; \& typedef unsigned char STORAGETYPE; \& \& typedef struct token { \& STORAGETYPE type; \& STORAGECLASS class; \& char token[STORAGE_TOKEN_LENGTH]; \& } TOKEN; \& \& typedef struct { \& unsigned char type; \& const char *data; \& struct iovec *iov; \& int iovcnt; \& size_t len; \& unsigned char nextmethod; \& void *private; \& time_t arrived; \& time_t expires; \& char *groups; \& int groupslen; \& TOKEN *token; \& } ARTHANDLE; \& \& typedef enum { \& SELFEXPIRE, \& SMARTNGNUM, \& EXPENSIVESTAT \& } PROBETYPE; \& \& typedef enum { \& SM_ALL, \& SM_HEAD, \& SM_CANCELLEDART \& } FLUSHTYPE; \& \& struct artngnum { \& char *groupname; \& ARTNUM artnum; \& }; \& \& 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); \& \& char *SMexplaintoken(const TOKEN token); \& \& void SMshutdown(void); \& \& int SMerrno; \& \& char *SMerrorstr; \& \& #include \& \& #define OV_NOSPACE ... \& \& typedef enum { \& OVSPACE, \& OVSORT, \& OVCUTOFFLOW, \& OVGROUPBASEDEXPIRE, \& OVSTATICSEARCH, \& OVSTATALL, \& OVCACHEKEEP, \& OVCACHEFREE \& } OVCTLTYPE; \& \& typedef enum { \& OVNEWSGROUP, \& OVARRIVED, \& OVNOSORT \& } OVSORTTYPE; \& \& typedef enum { \& OVADDCOMPLETED, \& OVADDFAILED, \& OVADDGROUPNOMATCH \& } OVADDRESULT; \& \& 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, time_t expires); \& \& 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, TOKEN *token); \& \& bool OVexpiregroup(char *group, int *lo, struct history *h); \& \& 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); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fBlibstorage\fR 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 \s-1API.\s0 .PP 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 \s-1API\s0 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 \&\fB\s-1OV\s0\fR is a common utility routines for accessing newsgroups and overview data independent of particular overview method. .PP The \fB\s-1OV\s0\fR function is to isolate the applications from the individual methods. All articles passed through the storage \s-1API\s0 are assumed to be in wire format. Wire format means \f(CW\*(C`\er\en\*(C'\fR at the end of lines, dot-stuffed lines (that is to say \f(CW\*(C`.\*(C'\fR at the beginning of lines which already start with \f(CW\*(C`.\*(C'\fR), and \f(CW\*(C`.\er\en\*(C'\fR at the end of article on \s-1NNTP\s0 stream are not stripped. This has a performance win when transferring articles. Note that 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 The \fBIsToken\fR function 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 The \fBTokenToText\fR function converts a token into a text string for output. .PP The \fBTextToToken\fR function converts a text string into a token. .PP The \fBSMsetup\fR function configures some parameters for use by the storage manager. \fItype\fR is one of following: .ie n .IP """SM_RDWR""" 4 .el .IP "\f(CWSM_RDWR\fR" 4 .IX Item "SM_RDWR" Allow read/write open for storage files (default is false). .ie n .IP """SM_PREOPEN""" 4 .el .IP "\f(CWSM_PREOPEN\fR" 4 .IX Item "SM_PREOPEN" Open all storage files at startup time and keep them (default is false). .PP \&\fIvalue\fR is the pointer which tells each type's value. It returns true if setup is successful, or false if not. .PP The \fBSMinit\fR function calls the setup function for all of the configured methods based on \fBSMsetup\fR. This function should be called prior to all other storage \s-1API\s0 functions which begin with \f(CW\*(C`SM\*(C'\fR except \fBSMsetup\fR. It returns true if initialization is successful or returns false if not. \&\fBSMinit\fR returns true, unless all storage methods fail initialization. .PP The \fBSMstore\fR function stores an article specified with \fIarticle\fR. The headers and body of the article are supplied to \fBSMstore\fR using the \&\fIiov\fR and \fIiovcnt\fR members of \fB\s-1ARTHANDLE\s0\fR. (\fIdata\fR and \fIprivate\fR are ignored by \fBSMstore\fR.) If \fIarrived\fR is specified, \fBSMstore\fR uses its value as article's arrival time; otherwise \fBSMstore\fR uses the current time for it. \fBSMstore\fR returns the token type or returns \fB\s-1TOKEN_EMPTY\s0\fR if the article is not stored because some error occurs or simply does not match any \fIuwildmat\fR expression in \fIstorage.conf\fR. \fBSMstore\fR fails if \&\fB\s-1SM_RDWR\s0\fR has not been set to true with \fBSMsetup\fR. .PP The \fBSMretrieve\fR function retrieves an article specified with \fItoken\fR. \&\fIamount\fR is the one of following which specifies retrieving type: .ie n .IP """RETR_ALL""" 4 .el .IP "\f(CWRETR_ALL\fR" 4 .IX Item "RETR_ALL" Retrieve the whole article. .ie n .IP """RETR_HEAD""" 4 .el .IP "\f(CWRETR_HEAD\fR" 4 .IX Item "RETR_HEAD" Retrieve the headers of the article. .ie n .IP """RETR_BODY""" 4 .el .IP "\f(CWRETR_BODY\fR" 4 .IX Item "RETR_BODY" Retrieve the body of the article. .ie n .IP """RETR_STAT""" 4 .el .IP "\f(CWRETR_STAT\fR" 4 .IX Item "RETR_STAT" Just check to see if the article exists. .PP \&\fBSMretrieve\fR provides the article data via the \fIdata\fR and \fIlen\fR members of \fB\s-1ARTHANDLE\s0\fR. (\fIiov\fR is not set by \fBSMretrieve\fR.) The data area indicated by \fB\s-1ARTHANDLE\s0\fR should not be modified. .PP The \fBSMnext\fR function is similar in function to \fBSMretrieve\fR except that it is intended for traversing the method's article store sequentially. To start a query, \fBSMnext\fR should be called with a \s-1NULL\s0 pointer \fB\s-1ARTHANDLE\s0\fR. Then \fBSMnext\fR returns \fB\s-1ARTHANDLE\s0\fR which should be used for the next query. If a \s-1NULL\s0 pointer \fB\s-1ARTHANDLE\s0\fR is returned, no articles are left to be queried. If \fIdata\fR of \fB\s-1ARTHANDLE\s0\fR is \s-1NULL\s0 pointer or \fIlen\fR of \&\fB\s-1ARTHANDLE\s0\fR is \f(CW0\fR, it indicates the article may be corrupted and should be cancelled by \fISMcancel\fR. The data area indicated by \fB\s-1ARTHANDLE\s0\fR should not be modified. .PP The \fBSMfreearticle\fR function frees all allocated memory used by \&\fBSMretrieve\fR and \fBSMnext\fR. If \fBSMnext\fR will be called with previously returned \fB\s-1ARTHANDLE\s0\fR, \fBSMfreearticle\fR should not be called as \fBSMnext\fR frees allocated memory internally. .PP The \fBSMcancel\fR function removes the article specified with \fItoken\fR. It returns true if cancellation is successful or returns false if not. \&\fBSMcancel\fR fails if \fB\s-1SM_RDWR\s0\fR has not been set to true with \fBSMsetup\fR. .PP The \fBSMprobe\fR function checks the token on \fB\s-1PROBETYPE\s0\fR. \fItype\fR is one of following: .ie n .IP """SELFEXPIRE""" 4 .el .IP "\f(CWSELFEXPIRE\fR" 4 .IX Item "SELFEXPIRE" Check to see if the method of the token has self expire functionality. .ie n .IP """SMARTNGNUM""" 4 .el .IP "\f(CWSMARTNGNUM\fR" 4 .IX Item "SMARTNGNUM" Get the newsgroup name and the article number of the token. .ie n .IP """EXPENSIVESTAT""" 4 .el .IP "\f(CWEXPENSIVESTAT\fR" 4 .IX Item "EXPENSIVESTAT" Check to see whether checking the existence of an article is expensive or not. .PP The \fBSMprintfiles\fR function shows file name or token usable by \fBfastrm\fR\|(8). .PP The \fBSMflushcacheddata\fR function flushes cached data on each storage method. \fItype\fR is one of following: .ie n .IP """SM_HEAD""" 4 .el .IP "\f(CWSM_HEAD\fR" 4 .IX Item "SM_HEAD" Flush cached header. .ie n .IP """SM_CANCELLEDART""" 4 .el .IP "\f(CWSM_CANCELLEDART\fR" 4 .IX Item "SM_CANCELLEDART" Flush the articles which should be cancelled. .ie n .IP """SM_ALL""" 4 .el .IP "\f(CWSM_ALL\fR" 4 .IX Item "SM_ALL" Flush all cached data. .PP The \fBSMexplaintoken\fR function returns a human-readable text string with a clear, decoded form of the storage \s-1API\s0 token. .PP The \fBSMshutdown\fR function calls the shutdown for each configured storage method and then frees any resources it has allocated for itself. .PP \&\fBSMerrno\fR and \fBSMerrorstr\fR indicate the reason of the last error concerning storage manager. .PP \&\fBOVopen\fR calls the setup function for configured method which is specified as \fIovmethod\fR in \fIinn.conf\fR. \fImode\fR is constructed from following: .ie n .IP """OV_READ""" 4 .el .IP "\f(CWOV_READ\fR" 4 .IX Item "OV_READ" Allow read open for the overview method. .ie n .IP """OV_WRITE""" 4 .el .IP "\f(CWOV_WRITE\fR" 4 .IX Item "OV_WRITE" Allow write open for the overview method. .PP This function should be called prior to all other \s-1OV\s0 functions which begin with \f(CW\*(C`OV\*(C'\fR. .PP The \fBOVctl\fR function probes or sets some parameters for the overview method. \&\fItype\fR is one of following: .ie n .IP """OVGROUPBASEDEXPIRE""" 4 .el .IP "\f(CWOVGROUPBASEDEXPIRE\fR" 4 .IX Item "OVGROUPBASEDEXPIRE" Setup how group-based expiry is done. .ie n .IP """OVCUTOFFLOW""" 4 .el .IP "\f(CWOVCUTOFFLOW\fR" 4 .IX Item "OVCUTOFFLOW" Do not add overview data if the data is under the lowest article. .ie n .IP """OVSORT""" 4 .el .IP "\f(CWOVSORT\fR" 4 .IX Item "OVSORT" Probe which key is suitable for the overview method. .ie n .IP """OVSPACE""" 4 .el .IP "\f(CWOVSPACE\fR" 4 .IX Item "OVSPACE" Probe the overview space usage. .ie n .IP """OVSTATALL""" 4 .el .IP "\f(CWOVSTATALL\fR" 4 .IX Item "OVSTATALL" Stat all the articles when \fBOVexpiregroup\fR is called. .ie n .IP """OVSTATICSEARCH""" 4 .el .IP "\f(CWOVSTATICSEARCH\fR" 4 .IX Item "OVSTATICSEARCH" Setup if results of \fBOVsearch\fR are stored in a static buffer and must be copied before the next call to \fBOVsearch\fR. .ie n .IP """OVCACHEKEEP""" 4 .el .IP "\f(CWOVCACHEKEEP\fR" 4 .IX Item "OVCACHEKEEP" Setup whether the cache should be kept. .ie n .IP """OVCACHEFREE""" 4 .el .IP "\f(CWOVCACHEFREE\fR" 4 .IX Item "OVCACHEFREE" Free the cache. .PP The \fBOVgroupstats\fR function retrieves the specified newsgroup information from the overview method. .PP The \fBOVgroupadd\fR function informs the overview method that the specified newsgroup is being added. .PP The \fBOVgroupdel\fR function informs the overview method that the specified newsgroup is being removed. .PP The \fBOVadd\fR function stores an overview data. .PP The \fBOVcancel\fR function requests the overview method delete overview data specified with token. .PP The \fBOVopensearch\fR function requests the overview method prepare overview data retrieval. The request range is determined by \fIlow\fR and \fIhigh\fR. The setting of \fB\s-1OVSTATICSEARCH\s0\fR determines how search result data must be handled. (Note that with some storage methods, each call to \&\fBOVopensearch\fR may cause internal storage to be remapped. Therefore, multiple simultaneous searches may require data to be copied in between \&\fBOVsearch\fR calls even if \fB\s-1OVSTATICSEARCH\s0\fR is false.) .PP The \fBOVsearch\fR function retrieves information, article number, overview data, or arrival time. It should be called with \s-1NULL\s0 handle when it is the first time; subsequent \fBOVsearch\fR calls should use the handle returned by the previous call to \fBOVsearch\fR. \fBOVsearch\fR returns true, unless it reaches \fIhigh\fR, which is specified by \fBOVopensearch\fR. Retrieved overview data are sorted by article number, and \fIlen\fR is \f(CW0\fR if there is no overview data for the article. Note that the retrieved data is not necessarily null-terminated; you should only rely on \fIlen\fR octets of overview data being present. .PP The \fBOVclosesearch\fR function frees all resources which have been allocated by \fBOVopensearch\fR. .PP The \fBOVgetartinfo\fR function retrieves the overview data and the token specified with \fIartnum\fR. .PP The \fBOVexpiregroup\fR function expires the overview data for the newsgroup. It checks the existence of the article and purges the overview data if the article no longer exists. If \fIgroupbaseexpiry\fR in \fIinn.conf\fR is true, \&\fBOVexpiregroup\fR also expires articles. .PP The \fBOVclose\fR function frees all resources which are used by the overview method. .SH "HISTORY" .IX Header "HISTORY" Written by Katsuhiro Kondou for InterNetNews. Converted to \s-1POD\s0 by Julien Elie. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBexpire\fR\|(8), \fBfastrm\fR\|(8), \fBinn.conf\fR\|(5), \fBlibinn_uwildmat\fR\|(3), \fBstorage.conf\fR\|(5).