1libinn(3) InterNetNews Documentation libinn(3)
2
6 libinn - InterNetNews library routines
7
9 #include "inn/libinn.h"
10 #define ISWHITE(c) ...
12 /* 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 /* Cancel-Lock routines. */
21 extern bool gen_cancel_lock(const char *msgid, const char *username,
22 char **canbuff);
23 extern bool gen_cancel_key(const char *hdrcontrol,
24 const char *hdrsupersedes,
25 const char *username, char **canbuff);
26 extern bool verify_cancel_key(const char *c_key_header,
27 const char *c_lock_header);
28 /* Opening the active file on a client. */
30 extern FILE *CAopen(FILE *FromServer, FILE *ToServer);
31 extern FILE *CAlistopen(FILE *FromServer, FILE *ToServer,
32 const char *request);
33 extern void CAclose(void);
34 /* File locking. */
36 enum inn_locktype
37 {
38 INN_LOCK_READ,
39 INN_LOCK_WRITE,
40 INN_LOCK_UNLOCK
41 };
42 extern bool inn_lock_file(int fd, enum inn_locktype type,
44 bool block);
45 /* NNTP functions. */
47 extern int NNTPlocalopen(FILE **FromServerp, FILE **ToServerp,
48 char *errbuff, size_t len);
49 extern int NNTPremoteopen(int port, FILE **FromServerp,
50 FILE **ToServerp, char *errbuff,
51 size_t len);
52 extern int NNTPconnect(const char *host, int port,
53 FILE **FromServerp, FILE **ToServerp,
54 char *errbuff, size_t len);
55 extern int NNTPsendarticle(char *text, FILE *ToServer,
56 bool terminate);
57 extern int NNTPsendpassword(char *server, FILE *FromServer,
58 FILE *ToServer);
59 /* Hash functions. */
61 typedef struct {
62 char hash[16];
63 } HASH;
64 extern HASH HashMessageID(const char *MessageID);
66 /* Other useful functions. */
68 extern char *inn_getfqdn(const char *domain);
69 extern char *GetModeratorAddress(FILE *FromServer, FILE *ToServer,
70 char *group, char *moderatormailer);
71 /* Miscellaneous. */
73 extern int GetResourceUsage(double *usertime, double *systime);
74 extern void Radix32(unsigned long value, char *buff);
75 extern char *ReadInDescriptor(int fd, struct stat *Sbp);
76 extern char *ReadInFile(const char *name, struct stat *Sbp);
77 /* Setting or clearing file descriptor flags. */
79 #include "inn/fdflag.h"
80 bool fdflag_close_exec(int fd, bool flag);
82 bool fdflag_nonblocking(socket_type fd, bool flag);
83
85 libinn is a library of utility routines for manipulating Usenet
86 articles and related data. The whole documentation of libinn routines
87 is split into several specific man pages besides this one:
88 libinn_clientlib(3), libinn_dbz(3), libinn_inndcomm(3), libinn_list(3),
89 libinn_qio(3), libinn_tst(3) and libinn_uwildmat(3).
90 MACROS
92 "ISWHITE" is a macro which tests whether its char argument is a space
93 or a tabulation.
94 HEADERS-RELATED ROUTINES
96 GenerateMessageID uses the current time, nnrpd's process ID, a global
97 static counter incrementing at each post in the same NNTP session, and
98 a fully qualified domain name, which is passed as an argument, to
99 create a Message-ID header field that is highly likely to be unique.
100 The returned value points to static space that is reused on subsequent
101 calls. If the argument is NULL, inn_getfqdn is called to find a
102 suitable FQDN (using domain as set in inn.conf to qualify the local
103 host name if local host cannot be resolved in DNS).
104 HeaderCleanFrom removes the extraneous information from the value of a
106 From or Reply-To header field and leaves just the official mailing
107 address. In particular, the following transformations are made to the
108 from parameter:
109 • address --> address
111 • address (stuff) --> address
113 • stuff <address> --> address
115 The transformations are simple, based on RFC 5536 which limits the
117 format of the header field.
118 DDstart, DDcheck, and DDend are used to set the Distribution header
120 field; the "DD" stands for Default Distribution. The distrib.pats file
121 is consulted to determine the proper value for the Distribution header
122 field after all newsgroups have been checked. DDstart begins the
123 parsing. It returns a pointer to an opaque handle that should be used
124 on subsequent calls. The FromServer and ToServer parameters should be
125 "FILE"'s connected to the NNTP server for input and output,
126 respectively. If either parameter is NULL, then an empty default will
127 ultimately be returned if the file is not locally available.
128 DDcheck should be called with the handle, h, returned by DDstart and a
130 newsgroup, group, to check. It can be called as often as necessary.
131 DDend releases any state maintained in the handle and returns an
133 allocated copy of the text that should be used for the Distribution
134 header field.
135 CANCEL-LOCK
137 These routines are available in libinn if INN was built with Cancel-
138 Lock support (otherwise they are stub functions which are always
139 returning false). The "configure" script automatically enables that
140 support if it finds libcanlock.
141 gen_cancel_lock expects a Message-ID, a username (possibly NULL) and
143 the address of a pointer where it will write elements suitable for the
144 body of a Cancel-Lock header field.
145 gen_cancel_key expects a Control header field body (possibly NULL), a
147 Supersedes header field body (possibly NULL), a username (possibly
148 NULL) and the address of a pointer where it will write elements
149 suitable for the body of a Cancel-Key header field. This function
150 extracts the Message-ID from the Control header field body or, if NULL,
151 from the Supersedes header field body. If the header field used for
152 that extraction is not correctly formatted, or they are both NULL, or
153 no Message-ID is found, it will result in a failure.
154 These functions return true if all the elements were written, false on
156 failure. The canbuff string will be allocated by these functions,
157 unless they return false. The caller is responsible for freeing it.
158 For each admin secret in the canlockadmin vector set in inn.conf, and
160 for each user secret set in the canlockuser vector set in inn.conf if
161 username is not NULL, gen_cancel_lock will generate in canbuff both
162 sha1 and sha256 Base64-encoded hashes. Regarding gen_cancel_key, it
163 will be for each admin secret in the canlockadmin vector if username is
164 NULL or for each user secret in the canlockuser vector if username is
165 not NULL.
166 verify_cancel_lock expects pointers to Cancel-Key and Cancel-Lock
168 header field bodies. This function verifies that c_key_header contains
169 an element matching one of those present in c_lock_header. It returns
170 true if at least one element matches. Otherwise, false is returned,
171 that is to say the cancel or supersede request cannot be authenticated.
172 CLIENT ACTIVE FILE
174 CAopen and CAclose provide news clients with access to the active file;
175 the "CA" stands for Client Active. CAopen opens the active file for
176 reading. It returns a pointer to an open "FILE", or NULL on error. If
177 a local or NFS-mounted copy exists, CAopen will use that file. The
178 FromServer and ToServer parameters should be "FILE"'s connected to the
179 NNTP server for input and output, respectively. See NNTPremoteopen or
180 NNTPlocalopen, below. If either parameter is NULL, then CAopen will
181 just return NULL if the file is not locally available. If they are not
182 NULL, CAopen will use them to query the NNTP server using the LIST
183 command to make a local temporary copy.
184 The CAlistopen sends a LIST command to the server and returns a
186 temporary file containing the results. The request parameter, if not
187 NULL, will be sent as an argument to the command. Unlike CAopen, this
188 routine will never use a locally-available copy of the active file.
189 CAclose closes the active file and removes any temporary file that
191 might have been created by CAopen or CAlistopen.
192 FILE LOCKING
194 inn_lock_file tries to lock the file descriptor fd. If block is true,
195 it will block until the lock can be made, otherwise it will return
196 false if the file cannot be locked. type is one of "INN_LOCK_READ",
197 "INN_LOCK_WRITE" or "INN_LOCK_UNLOCK". It returns false on failure or
198 true on success.
199 NNTP FUNCTIONS
201 NNTPlocalopen opens a connection to the private port of an InterNetNews
202 server running on the local host, if "HAVE_UNIX_DOMAIN_SOCKETS" in
203 include/config.h is defined. It returns "-1" on failure, or 0 on
204 success. FromServerp and ToServerp will be filled in with "FILE"'s
205 which can be used to communicate with the server. errbuff can either
206 be NULL or a pointer to a buffer at least 512 bytes long. If not NULL,
207 and the server refuses the connection, then it will be filled in with
208 the text of the server's reply. len should be the length of the
209 errbuff buffer. This routine is not for general use. If
210 "HAVE_UNIX_DOMAIN_SOCKETS" in include/config.h is not defined, this is
211 a stub routine, for compatibility with systems that have Unix-domain
212 stream sockets, and it then always returns "-1".
213 NNTPremoteopen does the same, except that it uses the server parameter
215 set in inn.conf as the local server, and opens a connection to the
216 port. Any client program can use this routine. It returns "-1" on
217 failure, or 0 on success.
218 NNTPconnect is the same as NNTPremoteopen except that the desired host
220 is given as the host parameter.
221 NNTPsendarticle writes text on ToServer using NNTP conventions for line
223 termination. The text should consist of one or more lines ending with
224 a newline. If terminate is true, then the routine will also write the
225 NNTP data-termination marker on the stream. It returns "-1" on
226 failure, or 0 on success.
227 NNTPsendpassword sends authentication information to an NNTP server by
229 finding the appropriate entry in the passwd.nntp file. server contains
230 the name of the host; the server parameter in inn.conf will be used if
231 server is NULL. FromServer and ToServer should be "FILE"'s that are
232 connected to the server. No action is taken if the specified host is
233 not listed in the password file.
234 HASHES
236 HashMessageID returns hashed Message-ID using MD5.
237 OTHER USEFUL FUNCTIONS
239 inn_getfqdn returns the fully qualified domain name of the local host.
240 domain is used to qualify the local host name if local host cannot be
241 resolved in DNS. The returned value points to newly-allocated memory
242 that the caller is responsible for freeing, or NULL on error.
243 GetModeratorAddress returns the mailing address of the moderator for
245 specified group or NULL on error. moderatormailer is used as its
246 address, if there is no matched moderator. See moderators(5) for
247 details on how the address is determined. GetModeratorAddress does no
248 checking to see if the specified group is actually moderated. The
249 returned value points to static space that is reused on subsequent
250 calls. The FromServer and ToServer parameters should be "FILE"'s
251 connected to the NNTP server for input and output, respectively. If
252 either of these parameters is NULL, then an attempt to get the list
253 from a local copy is made.
254 MISCELLANEOUS
256 GetResourceUsage fills in the usertime and systime parameters with the
257 total user and system time used by the current process and any children
258 it may have spawned. If "HAVE_GETRUSAGE" in include/config.h is
259 defined, it gets the values by doing a getrusage(2) system call;
260 otherwise it calls times(2). It returns "-1" on failure, or 0 on
261 success.
262 Radix32 converts the number in value into a radix-32 string into the
264 buffer pointed to by buff. The number is split into five-bit pieces
265 and each piece is converted into a character using the alphabet
266 "0..9a..v" to represent the numbers 0..32. Only the lowest 32 bits of
267 value are used, so buff needs only pointing to a buffer of eight bytes
268 (seven characters and the trailing "\0").
269 ReadInFile reads the file named name into allocated memory, appending a
271 terminating "\0" byte. It returns a pointer to the space, or NULL on
272 error. If Sbp is not NULL, it is taken as the address of a place to
273 store the results of a stat(2) call.
274 ReadInDescriptor performs the same function as ReadInFile except that
276 fd refers to an already-open file.
277 FILE DESCRIPTOR FLAGS
279 fdflag_close_exec can make a descriptor close-on-exec so that it is not
280 shared with any child processes. If the flag is true, the file is so
281 marked; if false, the close-on-exec mode is cleared. It returns false
282 on failure (or when the function is unsupported) or true on success.
283 fdflag_nonblocking enables (if flag is true) or disables (if flag is
285 false) non-blocking I/O on the indicated "socket_type" (which can be a
286 non-socket file descriptor on UNIX systems, but a "socket_type" is
287 expected on Windows). It returns false on failure or true on success.
288
290 #include "inn/fdflag.h"
291 #include "inn/libinn.h"
292 char *p;
294 char frombuff[256], errbuff[256];
295 FILE *F;
296 FILE *ToServer;
297 FILE *FromServer;
298 int port = 119;
299 strlcpy(frombuff, HDR(HDR__FROM), sizeof(frombuff));
301 HeaderCleanFrom(frombuff);
302 if ((F = CAopen(FromServer, ToServer)) == NULL)
304 Fatal("Can't open active file");
305 /* Don't pass the file on to our children. */
307 fdflag_close_exec(fileno(F), true);
308 /* Make a local copy. */
310 p = ReadInDescriptor(fileno(F), (struct stat *) NULL);
311 /* Close the file. */
313 CAclose();
314 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff,
316 sizeof(errbuff)) < 0)
317 Fatal("Can't connect to server");
318 if ((p = GetModeratorAddress(NULL, NULL, "comp.sources.unix",
320 "%s@example.com")) == NULL)
321 Fatal("Can't find moderator's address");
322
324 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
325 into POD by Julien Elie.
326
328 active(5), inn.conf(5), libinn_clientlib(3), libinn_dbz(3),
329 libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3),
330 libinn_uwildmat(3), moderators(5), passwd.nntp(5).
331INN 2.7.1 2023-03-07 libinn(3)