.\" Automatically generated by Pod::Man 4.14 (Pod::Simple 3.40) .\" .\" 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 "libinn 3" .TH libinn 3 "2023-03-07" "INN 2.7.1" "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" libinn \- InterNetNews library routines .SH "SYNOPSIS" .IX Header "SYNOPSIS" .Vb 1 \& #include "inn/libinn.h" \& \& #define ISWHITE(c) ... \& \& /* Headers\-related routines. */ \& extern char *GenerateMessageID(char *domain); \& extern void HeaderCleanFrom(char *from); \& extern struct _DDHANDLE *DDstart(FILE *FromServer, FILE *ToServer); \& extern void DDcheck(struct _DDHANDLE *h, char *group); \& extern char *DDend(struct _DDHANDLE *h); \& \& /* Cancel\-Lock routines. */ \& extern bool gen_cancel_lock(const char *msgid, const char *username, \& char **canbuff); \& extern bool gen_cancel_key(const char *hdrcontrol, \& const char *hdrsupersedes, \& const char *username, char **canbuff); \& extern bool verify_cancel_key(const char *c_key_header, \& const char *c_lock_header); \& \& /* Opening the active file on a client. */ \& extern FILE *CAopen(FILE *FromServer, FILE *ToServer); \& extern FILE *CAlistopen(FILE *FromServer, FILE *ToServer, \& const char *request); \& extern void CAclose(void); \& \& /* File locking. */ \& enum inn_locktype \& { \& INN_LOCK_READ, \& INN_LOCK_WRITE, \& INN_LOCK_UNLOCK \& }; \& \& extern bool inn_lock_file(int fd, enum inn_locktype type, \& bool block); \& \& /* NNTP functions. */ \& extern int NNTPlocalopen(FILE **FromServerp, FILE **ToServerp, \& char *errbuff, size_t len); \& extern int NNTPremoteopen(int port, FILE **FromServerp, \& FILE **ToServerp, char *errbuff, \& size_t len); \& extern int NNTPconnect(const char *host, int port, \& FILE **FromServerp, FILE **ToServerp, \& char *errbuff, size_t len); \& extern int NNTPsendarticle(char *text, FILE *ToServer, \& bool terminate); \& extern int NNTPsendpassword(char *server, FILE *FromServer, \& FILE *ToServer); \& \& /* Hash functions. */ \& typedef struct { \& char hash[16]; \& } HASH; \& \& extern HASH HashMessageID(const char *MessageID); \& \& /* Other useful functions. */ \& extern char *inn_getfqdn(const char *domain); \& extern char *GetModeratorAddress(FILE *FromServer, FILE *ToServer, \& char *group, char *moderatormailer); \& \& /* Miscellaneous. */ \& extern int GetResourceUsage(double *usertime, double *systime); \& extern void Radix32(unsigned long value, char *buff); \& extern char *ReadInDescriptor(int fd, struct stat *Sbp); \& extern char *ReadInFile(const char *name, struct stat *Sbp); \& \& /* Setting or clearing file descriptor flags. */ \& #include "inn/fdflag.h" \& \& bool fdflag_close_exec(int fd, bool flag); \& bool fdflag_nonblocking(socket_type fd, bool flag); .Ve .SH "DESCRIPTION" .IX Header "DESCRIPTION" \&\fIlibinn\fR is a library of utility routines for manipulating Usenet articles and related data. The whole documentation of \fIlibinn\fR routines is split into several specific man pages besides this one: \fBlibinn_clientlib\fR\|(3), \&\fBlibinn_dbz\fR\|(3), \fBlibinn_inndcomm\fR\|(3), \fBlibinn_list\fR\|(3), \fBlibinn_qio\fR\|(3), \&\fBlibinn_tst\fR\|(3) and \fBlibinn_uwildmat\fR\|(3). .SS "\s-1MACROS\s0" .IX Subsection "MACROS" \&\f(CW\*(C`ISWHITE\*(C'\fR is a macro which tests whether its char argument is a space or a tabulation. .SS "HEADERS-RELATED \s-1ROUTINES\s0" .IX Subsection "HEADERS-RELATED ROUTINES" \&\fBGenerateMessageID\fR uses the current time, \fBnnrpd\fR's process \s-1ID,\s0 a global static counter incrementing at each post in the same \s-1NNTP\s0 session, and a fully qualified domain name, which is passed as an argument, to create a Message-ID header field that is highly likely to be unique. The returned value points to static space that is reused on subsequent calls. If the argument is \s-1NULL,\s0 \&\fBinn_getfqdn\fR is called to find a suitable \s-1FQDN\s0 (using \fIdomain\fR as set in \&\fIinn.conf\fR to qualify the local host name if local host cannot be resolved in \s-1DNS\s0). .PP \&\fBHeaderCleanFrom\fR removes the extraneous information from the value of a From or Reply-To header field and leaves just the official mailing address. In particular, the following transformations are made to the \fIfrom\fR parameter: .IP "\(bu" 4 address \-\-> address .IP "\(bu" 4 address (stuff) \-\-> address .IP "\(bu" 4 stuff
\-\-> address .PP The transformations are simple, based on \s-1RFC\s0\ 5536 which limits the format of the header field. .PP \&\fBDDstart\fR, \fBDDcheck\fR, and \fBDDend\fR are used to set the Distribution header field; the \f(CW\*(C`DD\*(C'\fR stands for \fIDefault Distribution\fR. The \fIdistrib.pats\fR file is consulted to determine the proper value for the Distribution header field after all newsgroups have been checked. \fBDDstart\fR begins the parsing. It returns a pointer to an opaque handle that should be used on subsequent calls. The \fIFromServer\fR and \fIToServer\fR parameters should be \f(CW\*(C`FILE\*(C'\fR's connected to the \s-1NNTP\s0 server for input and output, respectively. If either parameter is \s-1NULL,\s0 then an empty default will ultimately be returned if the file is not locally available. .PP \&\fBDDcheck\fR should be called with the handle, \fIh\fR, returned by \fBDDstart\fR and a newsgroup, \fIgroup\fR, to check. It can be called as often as necessary. .PP \&\fBDDend\fR releases any state maintained in the handle and returns an allocated copy of the text that should be used for the Distribution header field. .SS "CANCEL-LOCK" .IX Subsection "CANCEL-LOCK" These routines are available in \fIlibinn\fR if \s-1INN\s0 was built with Cancel-Lock support (otherwise they are stub functions which are always returning false). The \f(CW\*(C`configure\*(C'\fR script automatically enables that support if it finds libcanlock. .PP \&\fBgen_cancel_lock\fR expects a Message-ID, a username (possibly \s-1NULL\s0) and the address of a pointer where it will write elements suitable for the body of a Cancel-Lock header field. .PP \&\fBgen_cancel_key\fR expects a Control header field body (possibly \s-1NULL\s0), a Supersedes header field body (possibly \s-1NULL\s0), a username (possibly \s-1NULL\s0) and the address of a pointer where it will write elements suitable for the body of a Cancel-Key header field. This function extracts the Message-ID from the Control header field body or, if \s-1NULL,\s0 from the Supersedes header field body. If the header field used for that extraction is not correctly formatted, or they are both \s-1NULL,\s0 or no Message-ID is found, it will result in a failure. .PP These functions return true if all the elements were written, false on failure. The \fIcanbuff\fR string will be allocated by these functions, unless they return false. The caller is responsible for freeing it. .PP For each admin secret in the \fIcanlockadmin\fR vector set in \fIinn.conf\fR, and for each user secret set in the \fIcanlockuser\fR vector set in \fIinn.conf\fR if \fIusername\fR is not \s-1NULL,\s0 \fBgen_cancel_lock\fR will generate in \fIcanbuff\fR both sha1 and sha256 Base64\-encoded hashes. Regarding \fBgen_cancel_key\fR, it will be for each admin secret in the \fIcanlockadmin\fR vector if \fIusername\fR is \s-1NULL\s0 or for each user secret in the \fIcanlockuser\fR vector if \fIusername\fR is not \s-1NULL.\s0 .PP \&\fBverify_cancel_lock\fR expects pointers to Cancel-Key and Cancel-Lock header field bodies. This function verifies that \fIc_key_header\fR contains an element matching one of those present in \fIc_lock_header\fR. It returns true if at least one element matches. Otherwise, false is returned, that is to say the cancel or supersede request cannot be authenticated. .SS "\s-1CLIENT ACTIVE FILE\s0" .IX Subsection "CLIENT ACTIVE FILE" \&\fBCAopen\fR and \fBCAclose\fR provide news clients with access to the \fIactive\fR file; the \f(CW\*(C`CA\*(C'\fR stands for \fIClient Active\fR. \fBCAopen\fR opens the \fIactive\fR file for reading. It returns a pointer to an open \f(CW\*(C`FILE\*(C'\fR, or \s-1NULL\s0 on error. If a local or NFS-mounted copy exists, \fBCAopen\fR will use that file. The \fIFromServer\fR and \fIToServer\fR parameters should be \f(CW\*(C`FILE\*(C'\fR's connected to the \s-1NNTP\s0 server for input and output, respectively. See \fBNNTPremoteopen\fR or \fBNNTPlocalopen\fR, below. If either parameter is \s-1NULL,\s0 then \fBCAopen\fR will just return \s-1NULL\s0 if the file is not locally available. If they are not \s-1NULL,\s0 \&\fBCAopen\fR will use them to query the \s-1NNTP\s0 server using the \s-1LIST\s0 command to make a local temporary copy. .PP The \fBCAlistopen\fR sends a \s-1LIST\s0 command to the server and returns a temporary file containing the results. The \fIrequest\fR parameter, if not \s-1NULL,\s0 will be sent as an argument to the command. Unlike \fBCAopen\fR, this routine will never use a locally-available copy of the \fIactive\fR file. .PP \&\fBCAclose\fR closes the \fIactive\fR file and removes any temporary file that might have been created by \fBCAopen\fR or \fBCAlistopen\fR. .SS "\s-1FILE LOCKING\s0" .IX Subsection "FILE LOCKING" \&\fBinn_lock_file\fR tries to lock the file descriptor \fIfd\fR. If \fIblock\fR is true, it will block until the lock can be made, otherwise it will return false if the file cannot be locked. \fItype\fR is one of \f(CW\*(C`INN_LOCK_READ\*(C'\fR, \&\f(CW\*(C`INN_LOCK_WRITE\*(C'\fR or \f(CW\*(C`INN_LOCK_UNLOCK\*(C'\fR. It returns false on failure or true on success. .SS "\s-1NNTP FUNCTIONS\s0" .IX Subsection "NNTP FUNCTIONS" \&\fBNNTPlocalopen\fR opens a connection to the private port of an InterNetNews server running on the local host, if \f(CW\*(C`HAVE_UNIX_DOMAIN_SOCKETS\*(C'\fR in \&\fIinclude/config.h\fR is defined. It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW0\fR on success. \fIFromServerp\fR and \fIToServerp\fR will be filled in with \f(CW\*(C`FILE\*(C'\fR's which can be used to communicate with the server. \fIerrbuff\fR can either be \&\s-1NULL\s0 or a pointer to a buffer at least 512 bytes long. If not \s-1NULL,\s0 and the server refuses the connection, then it will be filled in with the text of the server's reply. \fIlen\fR should be the length of the \fIerrbuff\fR buffer. This routine is not for general use. If \f(CW\*(C`HAVE_UNIX_DOMAIN_SOCKETS\*(C'\fR in \&\fIinclude/config.h\fR is not defined, this is a stub routine, for compatibility with systems that have Unix-domain stream sockets, and it then always returns \&\f(CW\*(C`\-1\*(C'\fR. .PP \&\fBNNTPremoteopen\fR does the same, except that it uses the \fIserver\fR parameter set in \fIinn.conf\fR as the local server, and opens a connection to the \fIport\fR. Any client program can use this routine. It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW0\fR on success. .PP \&\fBNNTPconnect\fR is the same as \fBNNTPremoteopen\fR except that the desired host is given as the \fIhost\fR parameter. .PP \&\fBNNTPsendarticle\fR writes \fItext\fR on \fIToServer\fR using \s-1NNTP\s0 conventions for line termination. The text should consist of one or more lines ending with a newline. If \fIterminate\fR is true, then the routine will also write the \s-1NNTP\s0 data-termination marker on the stream. It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW0\fR on success. .PP \&\fBNNTPsendpassword\fR sends authentication information to an \s-1NNTP\s0 server by finding the appropriate entry in the \fIpasswd.nntp\fR file. \fIserver\fR contains the name of the host; the \fIserver\fR parameter in \fIinn.conf\fR will be used if \&\fIserver\fR is \s-1NULL.\s0 \fIFromServer\fR and \fIToServer\fR should be \f(CW\*(C`FILE\*(C'\fR's that are connected to the server. No action is taken if the specified host is not listed in the password file. .SS "\s-1HASHES\s0" .IX Subsection "HASHES" \&\fBHashMessageID\fR returns hashed Message-ID using \s-1MD5.\s0 .SS "\s-1OTHER USEFUL FUNCTIONS\s0" .IX Subsection "OTHER USEFUL FUNCTIONS" \&\fBinn_getfqdn\fR returns the fully qualified domain name of the local host. \&\fIdomain\fR is used to qualify the local host name if local host cannot be resolved in \s-1DNS.\s0 The returned value points to newly-allocated memory that the caller is responsible for freeing, or \s-1NULL\s0 on error. .PP \&\fBGetModeratorAddress\fR returns the mailing address of the moderator for specified \fIgroup\fR or \s-1NULL\s0 on error. \fImoderatormailer\fR is used as its address, if there is no matched moderator. See \fBmoderators\fR\|(5) for details on how the address is determined. \fBGetModeratorAddress\fR does no checking to see if the specified group is actually moderated. The returned value points to static space that is reused on subsequent calls. The \fIFromServer\fR and \&\fIToServer\fR parameters should be \f(CW\*(C`FILE\*(C'\fR's connected to the \s-1NNTP\s0 server for input and output, respectively. If either of these parameters is \s-1NULL,\s0 then an attempt to get the list from a local copy is made. .SS "\s-1MISCELLANEOUS\s0" .IX Subsection "MISCELLANEOUS" \&\fBGetResourceUsage\fR fills in the \fIusertime\fR and \fIsystime\fR parameters with the total user and system time used by the current process and any children it may have spawned. If \f(CW\*(C`HAVE_GETRUSAGE\*(C'\fR in \fIinclude/config.h\fR is defined, it gets the values by doing a \fBgetrusage\fR\|(2) system call; otherwise it calls \&\fBtimes\fR\|(2). It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW0\fR on success. .PP \&\fBRadix32\fR converts the number in \fIvalue\fR into a radix\-32 string into the buffer pointed to by \fIbuff\fR. The number is split into five-bit pieces and each piece is converted into a character using the alphabet \f(CW\*(C`0..9a..v\*(C'\fR to represent the numbers \f(CW0..32\fR. Only the lowest 32 bits of \fIvalue\fR are used, so \fIbuff\fR needs only pointing to a buffer of eight bytes (seven characters and the trailing \f(CW\*(C`\e0\*(C'\fR). .PP \&\fBReadInFile\fR reads the file named \fIname\fR into allocated memory, appending a terminating \f(CW\*(C`\e0\*(C'\fR byte. It returns a pointer to the space, or \s-1NULL\s0 on error. If \fISbp\fR is not \s-1NULL,\s0 it is taken as the address of a place to store the results of a \fBstat\fR\|(2) call. .PP \&\fBReadInDescriptor\fR performs the same function as \fBReadInFile\fR except that \&\fIfd\fR refers to an already-open file. .SS "\s-1FILE DESCRIPTOR FLAGS\s0" .IX Subsection "FILE DESCRIPTOR FLAGS" \&\fBfdflag_close_exec\fR can make a descriptor \fIclose-on-exec\fR so that it is not shared with any child processes. If the flag is true, the file is so marked; if false, the \fIclose-on-exec\fR mode is cleared. It returns false on failure (or when the function is unsupported) or true on success. .PP \&\fBfdflag_nonblocking\fR enables (if \fIflag\fR is true) or disables (if \fIflag\fR is false) non-blocking I/O on the indicated \f(CW\*(C`socket_type\*(C'\fR (which can be a non-socket file descriptor on \s-1UNIX\s0 systems, but a \f(CW\*(C`socket_type\*(C'\fR is expected on Windows). It returns false on failure or true on success. .SH "EXAMPLES" .IX Header "EXAMPLES" .Vb 2 \& #include "inn/fdflag.h" \& #include "inn/libinn.h" \& \& char *p; \& char frombuff[256], errbuff[256]; \& FILE *F; \& FILE *ToServer; \& FILE *FromServer; \& int port = 119; \& \& strlcpy(frombuff, HDR(HDR_\|_FROM), sizeof(frombuff)); \& HeaderCleanFrom(frombuff); \& \& if ((F = CAopen(FromServer, ToServer)) == NULL) \& Fatal("Can\*(Aqt open active file"); \& \& /* Don\*(Aqt pass the file on to our children. */ \& fdflag_close_exec(fileno(F), true); \& \& /* Make a local copy. */ \& p = ReadInDescriptor(fileno(F), (struct stat *) NULL); \& \& /* Close the file. */ \& CAclose(); \& \& if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff, \& sizeof(errbuff)) < 0) \& Fatal("Can\*(Aqt connect to server"); \& \& if ((p = GetModeratorAddress(NULL, NULL, "comp.sources.unix", \& "%s@example.com")) == NULL) \& Fatal("Can\*(Aqt find moderator\*(Aqs address"); .Ve .SH "HISTORY" .IX Header "HISTORY" Written by Rich \f(CW$alz\fR for InterNetNews. Rewritten into \&\s-1POD\s0 by Julien Elie. .SH "SEE ALSO" .IX Header "SEE ALSO" \&\fBactive\fR\|(5), \fBinn.conf\fR\|(5), \fBlibinn_clientlib\fR\|(3), \fBlibinn_dbz\fR\|(3), \&\fBlibinn_inndcomm\fR\|(3), \fBlibinn_list\fR\|(3), \fBlibinn_qio\fR\|(3), \fBlibinn_tst\fR\|(3), \&\fBlibinn_uwildmat\fR\|(3), \fBmoderators\fR\|(5), \fBpasswd.nntp\fR\|(5).