chiark / gitweb /
wip manpage
[inn-innduct.git] / doc / man / libinn.3
1 .\" $Revision: 6124 $
2 .TH LIBINN 3
3 .SH NAME
4 libinn \- InterNetNews library routines
5 .SH SYNOPSIS
6 .nf
7 .ta \w'    unsigned long    'u
8 .B
9 #include "libinn.h"
10
11 .B "typedef struct _TIMEINFO {"
12 .B "    time_t  time;"
13 .B "    long    usec;"
14 .B "    long    tzone;
15 .B "} TIMEINFO;"
16
17 .B "char *"
18 .B "GenerateMessageID(domain)"
19 .B "    char    *domain;"
20
21 .B "void"
22 .B "HeaderCleanFrom(from)"
23 .B "    char    *from;"
24
25 .B "char *"
26 .B "HeaderFind(Article, Header, size)"
27 .B "    char    *Article;"
28 .B "    char    *Header;"
29 .B "    int     size;"
30
31 .B "FILE *"
32 .B "CAopen(FromServer, ToServer)"
33 .B "    FILE    *FromServer;"
34 .B "    FILE    *ToServer;"
35
36 .B "FILE *"
37 .B "CAlistopen(FromServer, ToServer, request)"
38 .B "    FILE    *FromServer;"
39 .B "    FILE    *ToServer;"
40 .B "    char    *request;"
41
42 .B "void"
43 .B "CAclose()"
44
45 .B "struct _DDHANDLE *"
46 .B "DDstart(FromServer, ToServer)"
47 .B "    FILE    *FromServer;"
48 .B "    FILE    *ToServer;"
49
50 .B "void"
51 .B "DDcheck(h, group)"
52 .B "    DDHANDLE        *h;"
53 .B "    char    *group;"
54
55 .B "char *"
56 .B "DDend(h)"
57 .B "    DDHANDLE        *h;"
58
59 .B "void"
60 .B "close_on_exec(fd, flag)"
61 .B "    int     fd;"
62 .B "    bool    flag;"
63
64 .B "int"
65 .B "nonblocking(fd, flag)"
66 .B "    int     fd;"
67 .B "    bool    flag;"
68
69 .B "bool"
70 .B "inn_lock_file(fd, type, flag)"
71 .B "    int     fd;"
72 .B "    LOCKTYPE        type;"
73 .B "    bool    block;"
74
75 .B "char *"
76 .B "GetFQDN(domain)"
77 .B "    char    *domain;"
78
79 .B "char *"
80 .B "GetModeratorAddress(FromServer, ToServer, group, moderatormailer)"
81 .B "    FILE    *FromServer;"
82 .B "    FILE    *ToServer;"
83 .B "    char    *group;"
84 .B "    char    *moderatormailer;"
85
86 .B "int"
87 .B "GetResourceUsage(usertime, systime)"
88 .B "    double  *usertime;"
89 .B "    double  *systime;"
90
91 .B "int"
92 .B "GetTimeInfo(now)"
93 .B "    TIMEINFO        *now;"
94
95 .B "int"
96 .B "NNTPlocalopen(FromServerp, ToServerp, errbuff)"
97 .B "    FILE    **FromServerp;"
98 .B "    FILE    **ToServerp;"
99 .B "    char    *errbuff;"
100
101 .B "int"
102 .B "NNTPremoteopen(port, FromServerp, ToServerp, errbuff)"
103 .B "    int     port;"
104 .B "    FILE    **FromServerp;"
105 .B "    FILE    **ToServerp;"
106 .B "    char    *errbuff;"
107
108 .B "int"
109 .B "NNTPconnect(host, port, FromServerp, ToServerp, errbuff)"
110 .B "    char    *host;"
111 .B "    int     port;"
112 .B "    FILE    **FromServerp;"
113 .B "    FILE    **ToServerp;"
114 .B "    char    *errbuff;"
115
116 .B "int"
117 .B "NNTPsendarticle(text, ToServer, Terminate)"
118 .B "    char    *text;"
119 .B "    FILE    *ToServer;"
120 .B "    int     Terminate;"
121
122 .B "int"
123 .B "NNTPsendpassword(server, FromServer, ToServer)"
124 .B "    char    *server;"
125 .B "    FILE    *FromServer;"
126 .B "    FILE    *ToServer;"
127
128 .B "void"
129 .B "Radix32(value, p)
130 .B "    unsigned long   value;"
131 .B "    char    *p;"
132
133 .B "char *"
134 .B "ReadInFile(name, Sbp)"
135 .B "    char    *name;"
136 .B "    struct stat     *Sbp;"
137
138 .B "char *"
139 .B "ReadInDescriptor(fd, Sbp)"
140 .B "    int     fd;"
141 .B "    struct stat     *Sbp;"
142
143 .B "HASH"
144 .B "HashMessageID(MessageID)"
145 .B "    const char *MessageID;"
146 .fi
147 .SH DESCRIPTION
148 .I Libinn
149 is a library of utility routines for manipulating Usenet articles and
150 related data.
151 It is not necessary to use the header file
152 .IR libinn.h ;
153 if it is not available, it is only necessary to properly declare the
154 .I TIMEINFO
155 datatype, as given above.
156 .PP
157 .I GenerateMessageID
158 uses the current time, process-ID, and fully-qualified domain name, which is
159 passed as an argument and used if local host can not be resolved or it is
160 different from ``domain'' set in
161 .IR inn.conf ,
162 to create a Message-ID header that is highly likely to be unique.
163 The returned value points to static space that is reused on subsequent calls.
164 .PP
165 .I HeaderCleanFrom
166 removes the extraneous information from the value of a ``From'' or ``Reply-To''
167 header and leaves just the official mailing address.
168 In particular, the following transformations are made to the
169 .I from
170 parameter:
171 .RS
172 .nf
173 .ta \w'stuff <address>  'u
174 address -->  address
175 address (stuff) -->  address
176 stuff <address> -->  address
177 .fi
178 .RE
179 The transformations are simple, based on RFC\ 1036 which limits the format
180 of the header.
181 .PP
182 .I HeaderFind
183 searches through
184 .I Article
185 looking for the specified
186 .IR Header .
187 .I Size
188 should be the length of the header name.
189 It returns a pointer to the value of the header, skipping leading whitespace,
190 or NULL if the header cannot be found.
191 .I Article
192 should be a standard C string containing the text of the article; the end
193 of the headers is indicated by a blank line \(em two consecutive \en
194 characters.
195 .PP
196 .I CAopen
197 and
198 .I CAclose
199 provide news clients with access to the active file; the ``CA'' stands for
200 .IR C lient
201 .IR A ctive.
202 .I CAopen
203 opens the
204 .I active
205 file for reading.
206 It returns a pointer to an open FILE, or NULL on error.
207 If a local or NFS-mounted copy exists,
208 .I CAopen
209 will use that file.
210 The
211 .I FromServer
212 and
213 .I ToServer
214 parameters should be FILE's connected to the NNTP server for input and
215 output, respectively.
216 See
217 .I NNTPremoteopen
218 or
219 .IR NNTPlocalopen ,
220 below.
221 If either parameter is NULL, then
222 .I CAopen
223 will just return NULL if the file is not locally available.
224 If they are not NULL,
225 .I CAopen
226 will use them to query the NNTP server using
227 the ``list'' command to make a local temporary copy.
228 .PP
229 The
230 .I CAlistopen
231 sends a ``list'' command to the server and returns a temporary file
232 containing the results.
233 The
234 .I request
235 parameter, if not NULL, will be sent as an argument to the command.
236 Unlike
237 .IR CAopen ,
238 this routine will never use a locally-available copy of the active file.
239 .PP
240 .I CAclose
241 closes the active file and removes any temporary file that might have
242 been created by
243 .I CAopen
244 or
245 .IR CAlistopen .
246 .PP
247 .I CloseOnExec
248 can make a descriptor ``close-on-exec'' so that it is not shared
249 with any child processes.
250 If the flag is non-zero, the file is so marked; if zero, the ``close-on-exec''
251 mode is cleared.
252 .PP
253 .IR DDstart ,
254 .IR DDcheck ,
255 and
256 .I DDend
257 are used to set the Distribution header; the ``DD'' stands for
258 .IR D efault
259 .IR D istribution.
260 The
261 .I distrib.pats
262 file is consulted to determine the proper value for the Distribution
263 header after all newsgroups have been checked.
264 .I DDstart
265 begins the parsing.
266 It returns a pointer to an opaque handle that should be used on subsequent
267 calls.
268 The
269 .I FromServer
270 and
271 .I ToServer
272 parameters should be FILE's connected to the NNTP server for input and
273 output, respectively.
274 If either parameter is NULL, then an empty default will ultimately be returned
275 if the file is not locally available.
276 .PP
277 .I DDcheck
278 should be called
279 with the handle,
280 .IR h ,
281 returned by
282 .I DDstart
283 and a newgroups,
284 .IR group ,
285 to check.
286 It can be called as often as necessary.
287 .PP
288 .I DDend
289 releases any state maintained in the handle and returns an allocated copy
290 of the text that should be used for the Distribution header.
291 .PP
292 .I SetNonBlocking
293 enables (if
294 .I flag
295 is non-zero) or disables (if
296 .I flag
297 is zero) non-blocking I/O on the indicated descriptor.
298 It returns \-1 on failure or zero on success.
299 .PP
300 .I inn_lock_file
301 tries to lock the file descriptor
302 .IR fd .
303 If
304 .I block
305 is true it will block until the lock can be made, otherwise
306 it will return false if the file cannot be locked.
307 .I type
308 is one of: INN_LOCK_READ, INN_LOCK_WRITE, or INN_LOCK_UNLOCK.
309 It returns false on failure or true on success.
310 .PP
311 .I GetFQDN
312 returns the fully-qualified domain name of the local host.
313 .I Domain
314 is used if local host can not be resolved.
315 The returned value points to static space that is reused on subsequent calls,
316 or NULL on error.
317 .PP
318 .I GetModeratorAddress
319 returns the mailing address of the moderator for specified
320 .I group
321 or NULL on error.
322 .I Moderatormailer
323 is used as its address, if there is no matched moderator.
324 See
325 .IR moderators (5)
326 for details on how the address is determined.
327 .I GetModeratorAddress
328 does no checking to see if the specified group is actually moderated.
329 The returned value points to static space that is reused on subsequent
330 calls.
331 The
332 .I FromServer
333 and
334 .I ToServer
335 parameters should be FILE's connected to the NNTP server for input and
336 output, respectively.  If either of these parameters is NULL, then an
337 attempt to get the list from a local copy is made.
338 .PP
339 .I GetResourceUsage
340 fills in the
341 .I usertime
342 and
343 .I systime
344 parameters with the total user and system time used by the current
345 process and any children it may have spawned.
346 If
347 .I <HAVE_GETRUSAGE in include/config.h>
348 is defined, it gets the values by doing a
349 .IR getrusage (2)
350 system call; otherwise it calls
351 .IR times (2).
352 It returns \-1 on failure, or zero on success.
353 .PP
354 .I GetTimeInfo
355 fills in the
356 .I now
357 parameter with information about the current time and tzone.
358 The ``time'' and ``usec'' fields will be filled in by a call to
359 .IR gettimeofday (2)
360 if
361 .I <$ac_cv_func_gettimeofday in config.cache>
362 is ``yes''.  Otherwise, the ``time'' field will be filled in by a call to
363 .IR time (2),
364 and the ``usec'' field will be set to zero.
365 The ``tzone'' field will be filled in with the current offset from GMT.
366 If
367 .I <HAVE_TM_GMTOFF in include/config.h>
368 is defined, this is done by calling
369 .IR localtime (3)
370 and taking the value of the ``tm_gmtoff'' field, negating it, and dividing
371 it by 60.
372 Otherwise, this is done by calling
373 .IR localtime (3)
374 and comparing the value with that returned by a call to
375 .IR gmtime (3).
376
377 For efficiency, the ``tzone'' field is only recalculated if more than an
378 hour pass passed since the last time
379 .I GetTimeInfo
380 has been called.
381 This routine returns \-1 on failure, or zero on success.
382 .PP
383 .I NNTPlocalopen
384 opens a connection to the private port of an InterNetNews server running on
385 the local host, if
386 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
387 is defined. 
388 It returns \-1 on failure, or zero on success.
389 .I FromServerp
390 and
391 .I ToServerp
392 will be filled in with FILE's which can be used to communicate
393 with the server.
394 .I Errbuff
395 can either be NULL or a pointer to a buffer at least 512 bytes long.
396 If not NULL, and the server refuses the connection, then it will be
397 filled in with the text of the server's reply.
398 This routine is not for general use.
399 If
400 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
401 is not defined, this
402 is a stub routine, for compatibility with systems that have Unix-domain
403 stream sockets.
404 It always returns \-1.
405 .PP
406 .I NNTPremoteopen
407 does the same except that it uses ``innconf->server''
408 as the local server, and opens a connection to the
409 .IR port .
410 Any client program can use this routine.
411 It returns \-1 on failure, or zero on success.
412 .PP
413 .I NNTPconnect
414 is the same as
415 .I NNTPremoteopen
416 except that the desired host is given as the
417 .I host
418 parameter.
419 .PP
420 .I NNTPsendarticle
421 writes
422 .I text
423 on
424 .I ToServer
425 using NNTP conventions for line termination.
426 The text should consist of one or more lines ending with a newline.
427 If
428 .I Terminate
429 is non-zero, then the routine will also write the NNTP data-termination
430 marker on the stream.
431 It returns \-1 on failure, or zero on success.
432 .PP
433 .I NNTPsendpassword
434 sends authentication information to an NNTP server by finding the appropriate
435 entry in the
436 .I passwd.nntp
437 file.
438 .I Server
439 contains the name of the host; ``innconf->server'' will be used if
440 .I server
441 is NULL.
442 .I FromServer
443 and
444 .I ToServer
445 should be FILE's that are connected to the server.
446 No action is taken if the specified host is not listed in the password file.
447 .PP
448 .I Radix32
449 converts the number in
450 .I value
451 into a radix-32 string into the buffer pointed to by
452 .IR p .
453 The number is split into five-bit pieces and each pieces is converted
454 into a character using the alphabet
455 .I "0..9a..v"
456 to represent the numbers 0..32.
457 Only the lowest 32 bits of
458 .I value
459 are used, so
460 .I p
461 need only point to a buffer of eight bytes (seven characters and the
462 trailing \e0).
463 .PP
464 .I ReadInFile
465 reads the file named
466 .I name
467 into allocated memory, appending a terminating \e0 byte.
468 It returns a pointer to the space, or NULL on error.
469 If
470 .I Sbp
471 is not NULL, it is taken as the address of a place to store the results
472 of a
473 .IR stat (2)
474 call.
475 .PP
476 .I ReadInDescriptor
477 performs the same function as
478 .I ReadInFile
479 except that
480 .I fd
481 refers to an already-open file.
482 .PP
483 .I HashMessageID
484 returns hashed message-id using MD5.
485 .SH EXAMPLES
486 .RS
487 .nf
488 char    *p;
489 char    *Article;
490 char    buff[256], errbuff[256];
491 FILE    *F;
492 FILE    *ToServer;
493 FILE    *FromServer;
494 int     port = 119;
495
496 if ((p = HeaderFind(Article, "From", 4)) == NULL)
497     Fatal("Can't find From line");
498 (void)strcpy(buff, p);
499 HeaderCleanFrom(buff);
500
501 if ((F = CAopen(FromServer, ToServer)) == NULL)
502     Fatal("Can't open active file");
503
504 /* Don't pass the file on to our children. */
505 CloseOnExec(fileno(F), 1);
506
507 /* Make a local copy. */
508 p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
509
510 /* Close the file. */
511 CAclose();
512
513 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff) < 0)
514     Fatal("Can't connect to server");
515
516 if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
517     Fatal("Can't find moderator's address");
518 .fi
519 .RE
520 .SH HISTORY
521 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
522 .de R$
523 This is revision \\$3, dated \\$4.
524 ..
525 .R$ $Id: libinn.3 6124 2003-01-14 06:03:29Z rra $
526 .SH "SEE ALSO"
527 active(5),
528 dbz(3z),
529 parsedate(3),
530 inn.conf(5),
531 inndcomm(3),
532 moderators(5),
533 passwd.nntp(5).