1libinn(3)                 InterNetNews Documentation                 libinn(3)
2
3
4

NAME

6       libinn - InterNetNews library routines
7

SYNOPSIS

9           #include "inn/libinn.h"
10
11           #define ISWHITE(c) ...
12
13           /* Headers-related routines. */
14           extern char *GenerateMessageID(char *domain);
15           extern void HeaderCleanFrom(char *from);
16           extern struct _DDHANDLE *DDstart(FILE *FromServer, FILE *ToServer);
17           extern void DDcheck(struct _DDHANDLE *h, char *group);
18           extern char *DDend(struct _DDHANDLE *h);
19
20           /* Opening the active file on a client. */
21           extern FILE *CAopen(FILE *FromServer, FILE *ToServer);
22           extern FILE *CAlistopen(FILE *FromServer, FILE *ToServer,
23                                   const char *request);
24           extern void CAclose(void);
25
26           /* File locking. */
27           enum inn_locktype
28           {
29               INN_LOCK_READ,
30               INN_LOCK_WRITE,
31               INN_LOCK_UNLOCK
32           };
33
34           extern bool inn_lock_file(int fd, enum inn_locktype type,
35                                     bool block);
36
37           /* NNTP functions. */
38           extern int NNTPlocalopen(FILE **FromServerp, FILE **ToServerp,
39                                    char *errbuff, size_t len);
40           extern int NNTPremoteopen(int port, FILE **FromServerp,
41                                     FILE **ToServerp, char *errbuff,
42                                     size_t len);
43           extern int NNTPconnect(const char *host, int port,
44                                  FILE **FromServerp, FILE **ToServerp,
45                                  char *errbuff, size_t len);
46           extern int NNTPsendarticle(char *text, FILE *ToServer,
47                                      bool terminate);
48           extern int NNTPsendpassword(char *server, FILE *FromServer,
49                                       FILE *ToServer);
50
51           /* Hash functions. */
52           typedef struct {
53               char hash[16];
54           } HASH;
55
56           extern HASH HashMessageID(const char *MessageID);
57
58           /* Other useful functions. */
59           extern char *inn_getfqdn(const char *domain);
60           extern char *GetModeratorAddress(FILE *FromServer, FILE *ToServer,
61                                            char *group, char *moderatormailer);
62
63           /* Miscellaneous. */
64           extern int GetResourceUsage(double *usertime, double *systime);
65           extern void Radix32(unsigned long value, char *buff);
66           extern char *ReadInDescriptor(int fd, struct stat *Sbp);
67           extern char *ReadInFile(const char *name, struct stat *Sbp);
68
69           /* Setting or clearing file descriptor flags. */
70           #include "inn/fdflag.h"
71
72           bool fdflag_close_exec(int fd, bool flag);
73           bool fdflag_nonblocking(socket_type fd, bool flag);
74

DESCRIPTION

76       libinn is a library of utility routines for manipulating Usenet
77       articles and related data.  The whole documentation of libinn routines
78       is split into several specific man pages besides this one:
79       libinn_clientlib(3), libinn_dbz(3), libinn_inndcomm(3), libinn_list(3),
80       libinn_qio(3), libinn_tst(3) and libinn_uwildmat(3).
81
82   MACROS
83       "ISWHITE" is a macro which tests whether its char argument is a space
84       or a tabulation.
85
86   HEADERS-RELATED ROUTINES
87       GenerateMessageID uses the current time, process-ID, and fully
88       qualified domain name, which is passed as an argument and used if local
89       host cannot be resolved or is different from domain set in inn.conf, to
90       create a Message-ID header field that is highly likely to be unique.
91       The returned value points to static space that is reused on subsequent
92       calls.
93
94       HeaderCleanFrom removes the extraneous information from the value of a
95       From or Reply-To header field and leaves just the official mailing
96       address.  In particular, the following transformations are made to the
97       from parameter:
98
99       •   address --> address
100
101       •   address (stuff) --> address
102
103       •   stuff <address> --> address
104
105       The transformations are simple, based on RFC 5536 which limits the
106       format of the header field.
107
108       DDstart, DDcheck, and DDend are used to set the Distribution header
109       field; the "DD" stands for Default Distribution.  The distrib.pats file
110       is consulted to determine the proper value for the Distribution header
111       field after all newsgroups have been checked.  DDstart begins the
112       parsing.  It returns a pointer to an opaque handle that should be used
113       on subsequent calls.  The FromServer and ToServer parameters should be
114       "FILE"'s connected to the NNTP server for input and output,
115       respectively.  If either parameter is NULL, then an empty default will
116       ultimately be returned if the file is not locally available.
117
118       DDcheck should be called with the handle, h, returned by DDstart and a
119       newsgroup, group, to check.  It can be called as often as necessary.
120
121       DDend releases any state maintained in the handle and returns an
122       allocated copy of the text that should be used for the Distribution
123       header field.
124
125   CLIENT ACTIVE FILE
126       CAopen and CAclose provide news clients with access to the active file;
127       the "CA" stands for Client Active.  CAopen opens the active file for
128       reading.  It returns a pointer to an open "FILE", or NULL on error.  If
129       a local or NFS-mounted copy exists, CAopen will use that file.  The
130       FromServer and ToServer parameters should be "FILE"'s connected to the
131       NNTP server for input and output, respectively.  See NNTPremoteopen or
132       NNTPlocalopen, below.  If either parameter is NULL, then CAopen will
133       just return NULL if the file is not locally available.  If they are not
134       NULL, CAopen will use them to query the NNTP server using the LIST
135       command to make a local temporary copy.
136
137       The CAlistopen sends a LIST command to the server and returns a
138       temporary file containing the results.  The request parameter, if not
139       NULL, will be sent as an argument to the command.  Unlike CAopen, this
140       routine will never use a locally-available copy of the active file.
141
142       CAclose closes the active file and removes any temporary file that
143       might have been created by CAopen or CAlistopen.
144
145   FILE LOCKING
146       inn_lock_file tries to lock the file descriptor fd.  If block is true,
147       it will block until the lock can be made, otherwise it will return
148       false if the file cannot be locked.  type is one of "INN_LOCK_READ",
149       "INN_LOCK_WRITE" or "INN_LOCK_UNLOCK".  It returns false on failure or
150       true on success.
151
152   NNTP FUNCTIONS
153       NNTPlocalopen opens a connection to the private port of an InterNetNews
154       server running on the local host, if "HAVE_UNIX_DOMAIN_SOCKETS" in
155       include/config.h is defined.  It returns "-1" on failure, or 0 on
156       success.  FromServerp and ToServerp will be filled in with "FILE"'s
157       which can be used to communicate with the server.  errbuff can either
158       be NULL or a pointer to a buffer at least 512 bytes long.  If not NULL,
159       and the server refuses the connection, then it will be filled in with
160       the text of the server's reply.  len should be the length of the
161       errbuff buffer.  This routine is not for general use.  If
162       "HAVE_UNIX_DOMAIN_SOCKETS" in include/config.h is not defined, this is
163       a stub routine, for compatibility with systems that have Unix-domain
164       stream sockets, and it then always returns "-1".
165
166       NNTPremoteopen does the same, except that it uses the server parameter
167       set in inn.conf as the local server, and opens a connection to the
168       port.  Any client program can use this routine.  It returns "-1" on
169       failure, or 0 on success.
170
171       NNTPconnect is the same as NNTPremoteopen except that the desired host
172       is given as the host parameter.
173
174       NNTPsendarticle writes text on ToServer using NNTP conventions for line
175       termination.  The text should consist of one or more lines ending with
176       a newline.  If terminate is true, then the routine will also write the
177       NNTP data-termination marker on the stream.  It returns "-1" on
178       failure, or 0 on success.
179
180       NNTPsendpassword sends authentication information to an NNTP server by
181       finding the appropriate entry in the passwd.nntp file.  server contains
182       the name of the host; the server parameter in inn.conf will be used if
183       server is NULL.  FromServer and ToServer should be "FILE"'s that are
184       connected to the server.  No action is taken if the specified host is
185       not listed in the password file.
186
187   HASHES
188       HashMessageID returns hashed Message-ID using MD5.
189
190   OTHER USEFUL FUNCTIONS
191       inn_getfqdn returns the fully qualified domain name of the local host.
192       domain is used to qualify the local host name if local host cannot be
193       resolved in DNS.  The returned value points to newly-allocated memory
194       that the caller is responsible for freeing, or NULL on error.
195
196       GetModeratorAddress returns the mailing address of the moderator for
197       specified group or NULL on error.  moderatormailer is used as its
198       address, if there is no matched moderator.  See moderators(5) for
199       details on how the address is determined.  GetModeratorAddress does no
200       checking to see if the specified group is actually moderated.  The
201       returned value points to static space that is reused on subsequent
202       calls.  The FromServer and ToServer parameters should be "FILE"'s
203       connected to the NNTP server for input and output, respectively.  If
204       either of these parameters is NULL, then an attempt to get the list
205       from a local copy is made.
206
207   MISCELLANEOUS
208       GetResourceUsage fills in the usertime and systime parameters with the
209       total user and system time used by the current process and any children
210       it may have spawned.  If "HAVE_GETRUSAGE" in include/config.h is
211       defined, it gets the values by doing a getrusage(2) system call;
212       otherwise it calls times(2).  It returns "-1" on failure, or 0 on
213       success.
214
215       Radix32 converts the number in value into a radix-32 string into the
216       buffer pointed to by buff.  The number is split into five-bit pieces
217       and each piece is converted into a character using the alphabet
218       "0..9a..v" to represent the numbers 0..32.  Only the lowest 32 bits of
219       value are used, so buff needs only pointing to a buffer of eight bytes
220       (seven characters and the trailing "\0").
221
222       ReadInFile reads the file named name into allocated memory, appending a
223       terminating "\0" byte.  It returns a pointer to the space, or NULL on
224       error.  If Sbp is not NULL, it is taken as the address of a place to
225       store the results of a stat(2) call.
226
227       ReadInDescriptor performs the same function as ReadInFile except that
228       fd refers to an already-open file.
229
230   FILE DESCRIPTOR FLAGS
231       fdflag_close_exec can make a descriptor close-on-exec so that it is not
232       shared with any child processes.  If the flag is true, the file is so
233       marked; if false, the close-on-exec mode is cleared.  It returns false
234       on failure (or when the function is unsupported) or true on success.
235
236       fdflag_nonblocking enables (if flag is true) or disables (if flag is
237       false) non-blocking I/O on the indicated "socket_type" (which can be a
238       non-socket file descriptor on UNIX systems, but a "socket_type" is
239       expected on Windows).  It returns false on failure or true on success.
240

EXAMPLES

242           #include "inn/fdflag.h"
243           #include "inn/libinn.h"
244
245           char *p;
246           char frombuff[256], errbuff[256];
247           FILE *F;
248           FILE *ToServer;
249           FILE *FromServer;
250           int port = 119;
251
252           strlcpy(frombuff, HDR(HDR__FROM), sizeof(frombuff));
253           HeaderCleanFrom(frombuff);
254
255           if ((F = CAopen(FromServer, ToServer)) == NULL)
256               Fatal("Can't open active file");
257
258           /* Don't pass the file on to our children. */
259           fdflag_close_exec(fileno(F), true);
260
261           /* Make a local copy. */
262           p = ReadInDescriptor(fileno(F), (struct stat *) NULL);
263
264           /* Close the file. */
265           CAclose();
266
267           if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff,
268                              sizeof(errbuff)) < 0)
269               Fatal("Can't connect to server");
270
271           if ((p = GetModeratorAddress(NULL, NULL, "comp.sources.unix",
272                                        "%s@example.com")) == NULL)
273               Fatal("Can't find moderator's address");
274

HISTORY

276       Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.  Rewritten
277       into POD by Julien Elie.
278

SEE ALSO

280       active(5), inn.conf(5), libinn_clientlib(3), libinn_dbz(3),
281       libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3),
282       libinn_uwildmat(3), moderators(5), passwd.nntp(5).
283
284
285
286INN 2.6.5                         2022-02-18                         libinn(3)
Impressum