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, process-ID, and fully
97 qualified domain name, which is passed as an argument and used if local
98 host cannot be resolved or is different from domain set in inn.conf, 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.
102 HeaderCleanFrom removes the extraneous information from the value of a
104 From or Reply-To header field and leaves just the official mailing
105 address. In particular, the following transformations are made to the
106 from parameter:
107 • address --> address
109 • address (stuff) --> address
111 • stuff <address> --> address
113 The transformations are simple, based on RFC 5536 which limits the
115 format of the header field.
116 DDstart, DDcheck, and DDend are used to set the Distribution header
118 field; the "DD" stands for Default Distribution. The distrib.pats file
119 is consulted to determine the proper value for the Distribution header
120 field after all newsgroups have been checked. DDstart begins the
121 parsing. It returns a pointer to an opaque handle that should be used
122 on subsequent calls. The FromServer and ToServer parameters should be
123 "FILE"'s connected to the NNTP server for input and output,
124 respectively. If either parameter is NULL, then an empty default will
125 ultimately be returned if the file is not locally available.
126 DDcheck should be called with the handle, h, returned by DDstart and a
128 newsgroup, group, to check. It can be called as often as necessary.
129 DDend releases any state maintained in the handle and returns an
131 allocated copy of the text that should be used for the Distribution
132 header field.
133 CANCEL-LOCK
135 These routines are available in libinn if INN was built with Cancel-
136 Lock support (otherwise they are stub functions which are always
137 returning false). The "configure" script automatically enables that
138 support if it finds libcanlock.
139 gen_cancel_lock expects a Message-ID, a username (possibly NULL) and
141 the address of a pointer where it will write elements suitable for the
142 body of a Cancel-Lock header field.
143 gen_cancel_key expects a Control header field body (possibly NULL), a
145 Supersedes header field body (possibly NULL), a username (possibly
146 NULL) and the address of a pointer where it will write elements
147 suitable for the body of a Cancel-Key header field. This function
148 extracts the Message-ID from the Control header field body or, if NULL,
149 from the Supersedes header field body. If the header field used for
150 that extraction is not correctly formatted, or they are both NULL, or
151 no Message-ID is found, it will result in a failure.
152 These functions return true if all the elements were written, false on
154 failure. The canbuff string will be allocated by these functions,
155 unless they return false. The caller is reponsible for freeing it.
156 For each admin secret in the canlockadmin vector set in inn.conf, and
158 for each user secret set in the canlockuser vector set in inn.conf if
159 username is not NULL, gen_cancel_lock will generate in canbuff both
160 sha1 and sha256 Base64-encoded hashes. Regarding gen_cancel_key, it
161 will be for each admin secret in the canlockadmin vector if username is
162 NULL or for each user secret in the canlockuser vector if username is
163 not NULL.
164 verify_cancel_lock expects pointers to Cancel-Key and Cancel-Lock
166 header field bodies. This function verifies that c_key_header contains
167 an element matching one of those present in c_lock_header. It returns
168 true if at least one element matches. Otherwise, false is returned,
169 that is to say the cancel or supersede request cannot be authenticated.
170 CLIENT ACTIVE FILE
172 CAopen and CAclose provide news clients with access to the active file;
173 the "CA" stands for Client Active. CAopen opens the active file for
174 reading. It returns a pointer to an open "FILE", or NULL on error. If
175 a local or NFS-mounted copy exists, CAopen will use that file. The
176 FromServer and ToServer parameters should be "FILE"'s connected to the
177 NNTP server for input and output, respectively. See NNTPremoteopen or
178 NNTPlocalopen, below. If either parameter is NULL, then CAopen will
179 just return NULL if the file is not locally available. If they are not
180 NULL, CAopen will use them to query the NNTP server using the LIST
181 command to make a local temporary copy.
182 The CAlistopen sends a LIST command to the server and returns a
184 temporary file containing the results. The request parameter, if not
185 NULL, will be sent as an argument to the command. Unlike CAopen, this
186 routine will never use a locally-available copy of the active file.
187 CAclose closes the active file and removes any temporary file that
189 might have been created by CAopen or CAlistopen.
190 FILE LOCKING
192 inn_lock_file tries to lock the file descriptor fd. If block is true,
193 it will block until the lock can be made, otherwise it will return
194 false if the file cannot be locked. type is one of "INN_LOCK_READ",
195 "INN_LOCK_WRITE" or "INN_LOCK_UNLOCK". It returns false on failure or
196 true on success.
197 NNTP FUNCTIONS
199 NNTPlocalopen opens a connection to the private port of an InterNetNews
200 server running on the local host, if "HAVE_UNIX_DOMAIN_SOCKETS" in
201 include/config.h is defined. It returns "-1" on failure, or 0 on
202 success. FromServerp and ToServerp will be filled in with "FILE"'s
203 which can be used to communicate with the server. errbuff can either
204 be NULL or a pointer to a buffer at least 512 bytes long. If not NULL,
205 and the server refuses the connection, then it will be filled in with
206 the text of the server's reply. len should be the length of the
207 errbuff buffer. This routine is not for general use. If
208 "HAVE_UNIX_DOMAIN_SOCKETS" in include/config.h is not defined, this is
209 a stub routine, for compatibility with systems that have Unix-domain
210 stream sockets, and it then always returns "-1".
211 NNTPremoteopen does the same, except that it uses the server parameter
213 set in inn.conf as the local server, and opens a connection to the
214 port. Any client program can use this routine. It returns "-1" on
215 failure, or 0 on success.
216 NNTPconnect is the same as NNTPremoteopen except that the desired host
218 is given as the host parameter.
219 NNTPsendarticle writes text on ToServer using NNTP conventions for line
221 termination. The text should consist of one or more lines ending with
222 a newline. If terminate is true, then the routine will also write the
223 NNTP data-termination marker on the stream. It returns "-1" on
224 failure, or 0 on success.
225 NNTPsendpassword sends authentication information to an NNTP server by
227 finding the appropriate entry in the passwd.nntp file. server contains
228 the name of the host; the server parameter in inn.conf will be used if
229 server is NULL. FromServer and ToServer should be "FILE"'s that are
230 connected to the server. No action is taken if the specified host is
231 not listed in the password file.
232 HASHES
234 HashMessageID returns hashed Message-ID using MD5.
235 OTHER USEFUL FUNCTIONS
237 inn_getfqdn returns the fully qualified domain name of the local host.
238 domain is used to qualify the local host name if local host cannot be
239 resolved in DNS. The returned value points to newly-allocated memory
240 that the caller is responsible for freeing, or NULL on error.
241 GetModeratorAddress returns the mailing address of the moderator for
243 specified group or NULL on error. moderatormailer is used as its
244 address, if there is no matched moderator. See moderators(5) for
245 details on how the address is determined. GetModeratorAddress does no
246 checking to see if the specified group is actually moderated. The
247 returned value points to static space that is reused on subsequent
248 calls. The FromServer and ToServer parameters should be "FILE"'s
249 connected to the NNTP server for input and output, respectively. If
250 either of these parameters is NULL, then an attempt to get the list
251 from a local copy is made.
252 MISCELLANEOUS
254 GetResourceUsage fills in the usertime and systime parameters with the
255 total user and system time used by the current process and any children
256 it may have spawned. If "HAVE_GETRUSAGE" in include/config.h is
257 defined, it gets the values by doing a getrusage(2) system call;
258 otherwise it calls times(2). It returns "-1" on failure, or 0 on
259 success.
260 Radix32 converts the number in value into a radix-32 string into the
262 buffer pointed to by buff. The number is split into five-bit pieces
263 and each piece is converted into a character using the alphabet
264 "0..9a..v" to represent the numbers 0..32. Only the lowest 32 bits of
265 value are used, so buff needs only pointing to a buffer of eight bytes
266 (seven characters and the trailing "\0").
267 ReadInFile reads the file named name into allocated memory, appending a
269 terminating "\0" byte. It returns a pointer to the space, or NULL on
270 error. If Sbp is not NULL, it is taken as the address of a place to
271 store the results of a stat(2) call.
272 ReadInDescriptor performs the same function as ReadInFile except that
274 fd refers to an already-open file.
275 FILE DESCRIPTOR FLAGS
277 fdflag_close_exec can make a descriptor close-on-exec so that it is not
278 shared with any child processes. If the flag is true, the file is so
279 marked; if false, the close-on-exec mode is cleared. It returns false
280 on failure (or when the function is unsupported) or true on success.
281 fdflag_nonblocking enables (if flag is true) or disables (if flag is
283 false) non-blocking I/O on the indicated "socket_type" (which can be a
284 non-socket file descriptor on UNIX systems, but a "socket_type" is
285 expected on Windows). It returns false on failure or true on success.
286
288 #include "inn/fdflag.h"
289 #include "inn/libinn.h"
290 char *p;
292 char frombuff[256], errbuff[256];
293 FILE *F;
294 FILE *ToServer;
295 FILE *FromServer;
296 int port = 119;
297 strlcpy(frombuff, HDR(HDR__FROM), sizeof(frombuff));
299 HeaderCleanFrom(frombuff);
300 if ((F = CAopen(FromServer, ToServer)) == NULL)
302 Fatal("Can't open active file");
303 /* Don't pass the file on to our children. */
305 fdflag_close_exec(fileno(F), true);
306 /* Make a local copy. */
308 p = ReadInDescriptor(fileno(F), (struct stat *) NULL);
309 /* Close the file. */
311 CAclose();
312 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff,
314 sizeof(errbuff)) < 0)
315 Fatal("Can't connect to server");
316 if ((p = GetModeratorAddress(NULL, NULL, "comp.sources.unix",
318 "%s@example.com")) == NULL)
319 Fatal("Can't find moderator's address");
320
322 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
323 into POD by Julien Elie.
324
326 active(5), inn.conf(5), libinn_clientlib(3), libinn_dbz(3),
327 libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3),
328 libinn_uwildmat(3), moderators(5), passwd.nntp(5).
329INN 2.7.0 2022-07-10 libinn(3)