4 libinn \- InterNetNews library routines
7 .ta \w' unsigned long 'u
11 .B "typedef struct _TIMEINFO {"
18 .B "GenerateMessageID(domain)"
22 .B "HeaderCleanFrom(from)"
26 .B "HeaderFind(Article, Header, size)"
32 .B "CAopen(FromServer, ToServer)"
33 .B " FILE *FromServer;"
37 .B "CAlistopen(FromServer, ToServer, request)"
38 .B " FILE *FromServer;"
45 .B "struct _DDHANDLE *"
46 .B "DDstart(FromServer, ToServer)"
47 .B " FILE *FromServer;"
51 .B "DDcheck(h, group)"
60 .B "close_on_exec(fd, flag)"
65 .B "nonblocking(fd, flag)"
70 .B "inn_lock_file(fd, type, flag)"
80 .B "GetModeratorAddress(FromServer, ToServer, group, moderatormailer)"
81 .B " FILE *FromServer;"
84 .B " char *moderatormailer;"
87 .B "GetResourceUsage(usertime, systime)"
88 .B " double *usertime;"
89 .B " double *systime;"
96 .B "NNTPlocalopen(FromServerp, ToServerp, errbuff)"
97 .B " FILE **FromServerp;"
98 .B " FILE **ToServerp;"
102 .B "NNTPremoteopen(port, FromServerp, ToServerp, errbuff)"
104 .B " FILE **FromServerp;"
105 .B " FILE **ToServerp;"
109 .B "NNTPconnect(host, port, FromServerp, ToServerp, errbuff)"
112 .B " FILE **FromServerp;"
113 .B " FILE **ToServerp;"
117 .B "NNTPsendarticle(text, ToServer, Terminate)"
119 .B " FILE *ToServer;"
123 .B "NNTPsendpassword(server, FromServer, ToServer)"
125 .B " FILE *FromServer;"
126 .B " FILE *ToServer;"
129 .B "Radix32(value, p)
130 .B " unsigned long value;"
134 .B "ReadInFile(name, Sbp)"
136 .B " struct stat *Sbp;"
139 .B "ReadInDescriptor(fd, Sbp)"
141 .B " struct stat *Sbp;"
144 .B "HashMessageID(MessageID)"
145 .B " const char *MessageID;"
149 is a library of utility routines for manipulating Usenet articles and
151 It is not necessary to use the header file
153 if it is not available, it is only necessary to properly declare the
155 datatype, as given above.
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
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.
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
173 .ta \w'stuff <address> 'u
175 address (stuff) --> address
176 stuff <address> --> address
179 The transformations are simple, based on RFC\ 1036 which limits the format
185 looking for the specified
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.
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
199 provide news clients with access to the active file; the ``CA'' stands for
206 It returns a pointer to an open FILE, or NULL on error.
207 If a local or NFS-mounted copy exists,
214 parameters should be FILE's connected to the NNTP server for input and
215 output, respectively.
221 If either parameter is NULL, then
223 will just return NULL if the file is not locally available.
224 If they are not NULL,
226 will use them to query the NNTP server using
227 the ``list'' command to make a local temporary copy.
231 sends a ``list'' command to the server and returns a temporary file
232 containing the results.
235 parameter, if not NULL, will be sent as an argument to the command.
238 this routine will never use a locally-available copy of the active file.
241 closes the active file and removes any temporary file that might have
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''
257 are used to set the Distribution header; the ``DD'' stands for
262 file is consulted to determine the proper value for the Distribution
263 header after all newsgroups have been checked.
266 It returns a pointer to an opaque handle that should be used on subsequent
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.
286 It can be called as often as necessary.
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.
295 is non-zero) or disables (if
297 is zero) non-blocking I/O on the indicated descriptor.
298 It returns \-1 on failure or zero on success.
301 tries to lock the file descriptor
305 is true it will block until the lock can be made, otherwise
306 it will return false if the file cannot be locked.
308 is one of: INN_LOCK_READ, INN_LOCK_WRITE, or INN_LOCK_UNLOCK.
309 It returns false on failure or true on success.
312 returns the fully-qualified domain name of the local host.
314 is used if local host can not be resolved.
315 The returned value points to static space that is reused on subsequent calls,
318 .I GetModeratorAddress
319 returns the mailing address of the moderator for specified
323 is used as its address, if there is no matched moderator.
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
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.
344 parameters with the total user and system time used by the current
345 process and any children it may have spawned.
347 .I <HAVE_GETRUSAGE in include/config.h>
348 is defined, it gets the values by doing a
350 system call; otherwise it calls
352 It returns \-1 on failure, or zero on success.
357 parameter with information about the current time and tzone.
358 The ``time'' and ``usec'' fields will be filled in by a call to
361 .I <$ac_cv_func_gettimeofday in config.cache>
362 is ``yes''. Otherwise, the ``time'' field will be filled in by a call to
364 and the ``usec'' field will be set to zero.
365 The ``tzone'' field will be filled in with the current offset from GMT.
367 .I <HAVE_TM_GMTOFF in include/config.h>
368 is defined, this is done by calling
370 and taking the value of the ``tm_gmtoff'' field, negating it, and dividing
372 Otherwise, this is done by calling
374 and comparing the value with that returned by a call to
377 For efficiency, the ``tzone'' field is only recalculated if more than an
378 hour pass passed since the last time
381 This routine returns \-1 on failure, or zero on success.
384 opens a connection to the private port of an InterNetNews server running on
386 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
388 It returns \-1 on failure, or zero on success.
392 will be filled in with FILE's which can be used to communicate
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.
400 .I <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h>
402 is a stub routine, for compatibility with systems that have Unix-domain
404 It always returns \-1.
407 does the same except that it uses ``innconf->server''
408 as the local server, and opens a connection to the
410 Any client program can use this routine.
411 It returns \-1 on failure, or zero on success.
416 except that the desired host is given as the
425 using NNTP conventions for line termination.
426 The text should consist of one or more lines ending with a newline.
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.
434 sends authentication information to an NNTP server by finding the appropriate
439 contains the name of the host; ``innconf->server'' will be used if
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.
449 converts the number in
451 into a radix-32 string into the buffer pointed to by
453 The number is split into five-bit pieces and each pieces is converted
454 into a character using the alphabet
456 to represent the numbers 0..32.
457 Only the lowest 32 bits of
461 need only point to a buffer of eight bytes (seven characters and the
467 into allocated memory, appending a terminating \e0 byte.
468 It returns a pointer to the space, or NULL on error.
471 is not NULL, it is taken as the address of a place to store the results
477 performs the same function as
481 refers to an already-open file.
484 returns hashed message-id using MD5.
490 char buff[256], errbuff[256];
496 if ((p = HeaderFind(Article, "From", 4)) == NULL)
497 Fatal("Can't find From line");
498 (void)strcpy(buff, p);
499 HeaderCleanFrom(buff);
501 if ((F = CAopen(FromServer, ToServer)) == NULL)
502 Fatal("Can't open active file");
504 /* Don't pass the file on to our children. */
505 CloseOnExec(fileno(F), 1);
507 /* Make a local copy. */
508 p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
510 /* Close the file. */
513 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff) < 0)
514 Fatal("Can't connect to server");
516 if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
517 Fatal("Can't find moderator's address");
521 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews.
523 This is revision \\$3, dated \\$4.
525 .R$ $Id: libinn.3 6124 2003-01-14 06:03:29Z rra $