.\" -*- mode: troff; coding: utf-8 -*- .\" Automatically generated by Pod::Man 5.01 (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 .. .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. .ie n \{\ . ds C` "" . ds C' "" 'br\} .el\{\ . 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 .\" ======================================================================== .\" .IX Title "libinn 3" .TH libinn 3 2024-02-12 "INN 2.7.2" "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); \& \& /* Reserving file descriptors. */ \& extern bool fdreserve(int fdnum); \& extern FILE *Fopen(const char *name, const char *mode, int fdindex); \& extern int Fclose(FILE *fp); \& \& /* Determining, setting and checking the limit on open file \& descriptors. */ \& extern int getfdlimit(void); \& extern int setfdlimit(unsigned int limit); \& extern bool isvalidfd(unsigned int fd); \& \& /* 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: libinn_clientlib(3), libinn_dbz(3), libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3) and libinn_uwildmat(3). .SS MACROS .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 ROUTINES" .IX Subsection "HEADERS-RELATED ROUTINES" \&\fBGenerateMessageID\fR uses the current time, \fBnnrpd\fR's process ID, a global static counter incrementing at each post in the same NNTP 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 NULL, \&\fBinn_getfqdn\fR is called to find a suitable FQDN (using \fIdomain\fR as set in \&\fIinn.conf\fR to qualify the local host name if local host cannot be resolved in DNS). .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 RFC\ 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 NNTP server for input and output, respectively. If either parameter is NULL, 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 INN 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 NULL) 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 NULL), a Supersedes header field body (possibly NULL), a username (possibly NULL) 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 NULL, from the Supersedes header field body. If the header field used for that extraction is not correctly formatted, or they are both NULL, 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 NULL, \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 NULL or for each user secret in the \fIcanlockuser\fR vector if \fIusername\fR is not NULL. .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 "CLIENT ACTIVE FILE" .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 NULL 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 NNTP server for input and output, respectively. See \fBNNTPremoteopen\fR or \fBNNTPlocalopen\fR, below. If either parameter is NULL, then \fBCAopen\fR will just return NULL if the file is not locally available. If they are not NULL, \&\fBCAopen\fR will use them to query the NNTP server using the LIST command to make a local temporary copy. .PP The \fBCAlistopen\fR sends a LIST command to the server and returns a temporary file containing the results. The \fIrequest\fR parameter, if not NULL, 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 "FILE LOCKING" .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 "NNTP FUNCTIONS" .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(CW\*(C`0\*(C'\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 NULL or a pointer to a buffer at least 512 bytes long. If not NULL, 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(CW\*(C`0\*(C'\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 NNTP 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 NNTP data-termination marker on the stream. It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW\*(C`0\*(C'\fR on success. .PP \&\fBNNTPsendpassword\fR sends authentication information to an NNTP 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 NULL. \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 HASHES .IX Subsection "HASHES" \&\fBHashMessageID\fR returns hashed Message-ID using MD5. .SS "OTHER USEFUL FUNCTIONS" .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 DNS. The returned value points to newly-allocated memory that the caller is responsible for freeing, or NULL on error. .PP \&\fBGetModeratorAddress\fR returns the mailing address of the moderator for specified \fIgroup\fR or NULL on error. \fImoderatormailer\fR is used as its address, if there is no matched moderator. See moderators(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 NNTP server for input and output, respectively. If either of these parameters is NULL, then an attempt to get the list from a local copy is made. .SS MISCELLANEOUS .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 getrusage(2) system call; otherwise it calls times(2). It returns \f(CW\*(C`\-1\*(C'\fR on failure, or \f(CW\*(C`0\*(C'\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(CW\*(C`0..32\*(C'\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 NULL on error. If \fISbp\fR is not NULL, it is taken as the address of a place to store the results of a stat(2) call. .PP \&\fBReadInDescriptor\fR performs the same function as \fBReadInFile\fR except that \&\fIfd\fR refers to an already-open file. .SS "FILE DESCRIPTOR RESERVATION" .IX Subsection "FILE DESCRIPTOR RESERVATION" \&\fBfdreserve\fR permits reserving \fIfdnum\fR file descriptors for future use. On platforms that have a stdio limitation, such as 64\-bit Solaris versions prior to 11.0, all 32\-bit Solaris versions and 32\-bit applications running on 64\-bit Solaris, low-numbered file descriptors can then be kept and re-used for stdio. Without this mechanism, some essential files like the \fIhistory\fR file may not have any file descriptor left when being reopened after a closure for some operations, and stdio would fail. .PP These file descriptors all read \f(CW\*(C`/dev/null\*(C'\fR, until \fBFopen\fR is called on them. If \fIfdnum\fR is \f(CW\*(C`0\*(C'\fR or negative, all reserved file descriptors are closed. Otherwise, \fIfdnum\fR file descriptors are reserved. If this function is called again with a higher \fIfdnum\fR value, it reserves more file descriptors; with a lower \fIfdnum\fR value, it closes the supernumerary reserved file descriptors. It returns true when all the file descriptors have been successfully reserved, and false otherwise, in which case all the reserved file descriptors are closed, even if some of them were previously in use. .PP \&\fBFopen\fR opens the file \fIname\fR in the given \fImode\fR, using the file descriptor in position \fIfdindex\fR in the reserved file descriptors. If \fIfdindex\fR is lower than the number of reserved file descriptors, \fBFopen\fR uses the corresponding one. Otherwise, it just calls fopen(2) without re-using a reserved file descriptor. It returns a pointer to a FILE struct, or NULL on failure. .PP \&\fBFclose\fR closes the file descriptor used for \fIfp\fR without keeping it, unless this file descriptor was a reserved one, in which case it is kept (and read \&\f(CW\*(C`/dev/null\*(C'\fR). It returns \f(CW\*(C`0\*(C'\fR on success. Any other value (like EOF) is a failure. .SS "FILE DESCRIPTOR LIMITS" .IX Subsection "FILE DESCRIPTOR LIMITS" \&\fBgetfdlimit\fR returns the limit on open file descriptors. It uses the getrlimit(2) function when available. If not, it tries sysconf(2), then getdtablesize(2), then ulimit(2), then a possible hard-coded \f(CW\*(C`NOFILE\*(C'\fR constant in the \fIsys/param.h\fR system header, or then falls back to the POSIX-guaranteed minimum of 20. .PP \&\fBsetfdlimit\fR sets the limit on open file descriptors to the given parameter \&\fIlimit\fR. It uses the setrlimit(2) function when available. It returns \&\f(CW\*(C`1\*(C'\fR on success, and \f(CW\*(C`\-1\*(C'\fR on failure (when setrlimit(2) is not available or \&\fIlimit\fR is higher than select(2) can handle, checking against \f(CW\*(C`FD_SETSIZE\*(C'\fR). .PP \&\fBisvalidfd\fR returns true if \fIfd\fR is not higher than the system supports, and false otherwise. .SS "FILE DESCRIPTOR FLAGS" .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 UNIX 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 $alz for InterNetNews. Rewritten into POD by Julien Elie. .SH "SEE ALSO" .IX Header "SEE ALSO" active(5), inn.conf(5), libinn_clientlib(3), libinn_dbz(3), libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3), libinn_uwildmat(3), moderators(5), passwd.nntp(5).