1LIBINN(3) Library Functions Manual LIBINN(3)
2
6 libinn - InterNetNews library routines
7
9 #include "libinn.h"
10 typedef struct _TIMEINFO {
12 time_t time;
13 long usec;
14 long tzone;
15 } TIMEINFO;
16 char *
18 GenerateMessageID(domain)
19 char *domain;
20 void
22 HeaderCleanFrom(from)
23 char *from;
24 char *
26 HeaderFind(Article, Header, size)
27 char *Article;
28 char *Header;
29 int size;
30 FILE *
32 CAopen(FromServer, ToServer)
33 FILE *FromServer;
34 FILE *ToServer;
35 FILE *
37 CAlistopen(FromServer, ToServer, request)
38 FILE *FromServer;
39 FILE *ToServer;
40 char *request;
41 void
43 CAclose()
44 struct _DDHANDLE *
46 DDstart(FromServer, ToServer)
47 FILE *FromServer;
48 FILE *ToServer;
49 void
51 DDcheck(h, group)
52 DDHANDLE *h;
53 char *group;
54 char *
56 DDend(h)
57 DDHANDLE *h;
58 void
60 close_on_exec(fd, flag)
61 int fd;
62 bool flag;
63 int
65 nonblocking(fd, flag)
66 int fd;
67 bool flag;
68 bool
70 inn_lock_file(fd, type, flag)
71 int fd;
72 LOCKTYPE type;
73 bool block;
74 char *
76 GetFQDN(domain)
77 char *domain;
78 char *
80 GetModeratorAddress(FromServer, ToServer, group, moderatormailer)
81 FILE *FromServer;
82 FILE *ToServer;
83 char *group;
84 char *moderatormailer;
85 int
87 GetResourceUsage(usertime, systime)
88 double *usertime;
89 double *systime;
90 int
92 GetTimeInfo(now)
93 TIMEINFO *now;
94 int
96 NNTPlocalopen(FromServerp, ToServerp, errbuff)
97 FILE **FromServerp;
98 FILE **ToServerp;
99 char *errbuff;
100 int
102 NNTPremoteopen(port, FromServerp, ToServerp, errbuff)
103 int port;
104 FILE **FromServerp;
105 FILE **ToServerp;
106 char *errbuff;
107 int
109 NNTPconnect(host, port, FromServerp, ToServerp, errbuff)
110 char *host;
111 int port;
112 FILE **FromServerp;
113 FILE **ToServerp;
114 char *errbuff;
115 int
117 NNTPsendarticle(text, ToServer, Terminate)
118 char *text;
119 FILE *ToServer;
120 int Terminate;
121 int
123 NNTPsendpassword(server, FromServer, ToServer)
124 char *server;
125 FILE *FromServer;
126 FILE *ToServer;
127 void
129 Radix32(value, p)
130 unsigned long value;
131 char *p;
132 char *
134 ReadInFile(name, Sbp)
135 char *name;
136 struct stat *Sbp;
137 char *
139 ReadInDescriptor(fd, Sbp)
140 int fd;
141 struct stat *Sbp;
142 HASH
144 HashMessageID(MessageID)
145 const char *MessageID;
146
148 Libinn is a library of utility routines for manipulating Usenet arti‐
149 cles and related data. It is not necessary to use the header file lib‐
150 inn.h; if it is not available, it is only necessary to properly declare
151 the TIMEINFO datatype, as given above.
152 GenerateMessageID uses the current time, process-ID, and fully-quali‐
154 fied domain name, which is passed as an argument and used if local host
155 can not be resolved or it is different from ``domain'' set in inn.conf,
156 to create a Message-ID header that is highly likely to be unique. The
157 returned value points to static space that is reused on subsequent
158 calls.
159 HeaderCleanFrom removes the extraneous information from the value of a
161 ``From'' or ``Reply-To'' header and leaves just the official mailing
162 address. In particular, the following transformations are made to the
163 from parameter:
164 address --> address
165 address (stuff) --> address
166 stuff <address> --> address
167 The transformations are simple, based on RFC 1036 which limits the for‐
168 mat of the header.
169 HeaderFind searches through Article looking for the specified Header.
171 Size should be the length of the header name. It returns a pointer to
172 the value of the header, skipping leading whitespace, or NULL if the
173 header cannot be found. Article should be a standard C string contain‐
174 ing the text of the article; the end of the headers is indicated by a
175 blank line — two consecutive \n characters.
176 CAopen and CAclose provide news clients with access to the active file;
178 the ``CA'' stands for Client Active. CAopen opens the active file for
179 reading. It returns a pointer to an open FILE, or NULL on error. If a
180 local or NFS-mounted copy exists, CAopen will use that file. The From‐
181 Server and ToServer parameters should be FILE's connected to the NNTP
182 server for input and output, respectively. See NNTPremoteopen or NNT‐
183 Plocalopen, below. If either parameter is NULL, then CAopen will just
184 return NULL if the file is not locally available. If they are not
185 NULL, CAopen will use them to query the NNTP server using the ``list''
186 command to make a local temporary copy.
187 The CAlistopen sends a ``list'' command to the server and returns a
189 temporary file containing the results. The request parameter, if not
190 NULL, will be sent as an argument to the command. Unlike CAopen, this
191 routine will never use a locally-available copy of the active file.
192 CAclose closes the active file and removes any temporary file that
194 might have been created by CAopen or CAlistopen.
195 CloseOnExec can make a descriptor ``close-on-exec'' so that it is not
197 shared with any child processes. If the flag is non-zero, the file is
198 so marked; if zero, the ``close-on-exec'' mode is cleared.
199 DDstart, DDcheck, and DDend are used to set the Distribution header;
201 the ``DD'' stands for Default Distribution. The distrib.pats file is
202 consulted to determine the proper value for the Distribution header
203 after all newsgroups have been checked. DDstart begins the parsing.
204 It returns a pointer to an opaque handle that should be used on subse‐
205 quent calls. The FromServer and ToServer parameters should be FILE's
206 connected to the NNTP server for input and output, respectively. If
207 either parameter is NULL, then an empty default will ultimately be
208 returned if the file is not locally available.
209 DDcheck should be called with the handle, h, returned by DDstart and a
211 newgroups, group, to check. It can be called as often as necessary.
212 DDend releases any state maintained in the handle and returns an allo‐
214 cated copy of the text that should be used for the Distribution header.
215 SetNonBlocking enables (if flag is non-zero) or disables (if flag is
217 zero) non-blocking I/O on the indicated descriptor. It returns -1 on
218 failure or zero on success.
219 inn_lock_file tries to lock the file descriptor fd. If block is true
221 it will block until the lock can be made, otherwise it will return
222 false if the file cannot be locked. type is one of: INN_LLOCK_READ,
223 INN_LLOCK_WRITE, or INN_LOCK_UNLOCK. It returns false on failure or
224 true on success.
225 GetFQDN returns the fully-qualified domain name of the local host.
227 Domain is used if local host can not be resolved. The returned value
228 points to static space that is reused on subsequent calls, or NULL on
229 error.
230 GetModeratorAddress returns the mailing address of the moderator for
232 specified group or NULL on error. Moderatormailer is used as its
233 address, if there is no matched moderator. See moderators(5) for
234 details on how the address is determined. GetModeratorAddress does no
235 checking to see if the specified group is actually moderated. The
236 returned value points to static space that is reused on subsequent
237 calls. The FromServer and ToServer parameters should be FILE's con‐
238 nected to the NNTP server for input and output, respectively. If
239 either of these parameters is NULL, then an attempt to get the list
240 from a local copy is made.
241 GetResourceUsage fills in the usertime and systime parameters with the
243 total user and system time used by the current process and any children
244 it may have spawned. If <HAVE_GETRUSAGE in include/config.h> is
245 defined, it gets the values by doing a getrusage(2) system call; other‐
246 wise it calls times(2). It returns -1 on failure, or zero on success.
247 GetTimeInfo fills in the now parameter with information about the cur‐
249 rent time and tzone. The ``time'' and ``usec'' fields will be filled
250 in by a call to gettimeofday(2) if <$ac_cv_func_gettimeofday in con‐
251 fig.cache> is ``yes''. Otherwise, the ``time'' field will be filled in
252 by a call to time(2), and the ``usec'' field will be set to zero. The
253 ``tzone'' field will be filled in with the current offset from GMT. If
254 <HAVE_TM_GMTOFF in include/config.h> is defined, this is done by call‐
255 ing localtime(3) and taking the value of the ``tm_gmtoff'' field,
256 negating it, and dividing it by 60. Otherwise, this is done by calling
257 localtime(3) and comparing the value with that returned by a call to
258 gmtime(3).
259 For efficiency, the ``tzone'' field is only recalculated if more than
261 an hour pass passed since the last time GetTimeInfo has been called.
262 This routine returns -1 on failure, or zero on success.
263 NNTPlocalopen opens a connection to the private port of an InterNetNews
265 server running on the local host, if <HAVE_UNIX_DOMAIN_SOCKETS in
266 include/config.h> is defined. It returns -1 on failure, or zero on
267 success. FromServerp and ToServerp will be filled in with FILE's which
268 can be used to communicate with the server. Errbuff can either be NULL
269 or a pointer to a buffer at least 512 bytes long. If not NULL, and the
270 server refuses the connection, then it will be filled in with the text
271 of the server's reply. This routine is not for general use. If
272 <HAVE_UNIX_DOMAIN_SOCKETS in include/config.h> is not defined, this is
273 a stub routine, for compatibility with systems that have Unix-domain
274 stream sockets. It always returns -1.
275 NNTPremoteopen does the same except that it uses ``innconf->server'' as
277 the local server, and opens a connection to the port. Any client pro‐
278 gram can use this routine. It returns -1 on failure, or zero on suc‐
279 cess.
280 NNTPconnect is the same as NNTPremoteopen except that the desired host
282 is given as the host parameter.
283 NNTPsendarticle writes text on ToServer using NNTP conventions for line
285 termination. The text should consist of one or more lines ending with
286 a newline. If Terminate is non-zero, then the routine will also write
287 the NNTP data-termination marker on the stream. It returns -1 on fail‐
288 ure, or zero on success.
289 NNTPsendpassword sends authentication information to an NNTP server by
291 finding the appropriate entry in the passwd.nntp file. Server contains
292 the name of the host; ``innconf->server'' will be used if server is
293 NULL. FromServer and ToServer should be FILE's that are connected to
294 the server. No action is taken if the specified host is not listed in
295 the password file.
296 Radix32 converts the number in value into a radix-32 string into the
298 buffer pointed to by p. The number is split into five-bit pieces and
299 each pieces is converted into a character using the alphabet 0..9a..v
300 to represent the numbers 0..32. Only the lowest 32 bits of value are
301 used, so p need only point to a buffer of eight bytes (seven characters
302 and the trailing \0).
303 ReadInFile reads the file named name into allocated memory, appending a
305 terminating \0 byte. It returns a pointer to the space, or NULL on
306 error. If Sbp is not NULL, it is taken as the address of a place to
307 store the results of a stat(2) call.
308 ReadInDescriptor performs the same function as ReadInFile except that
310 fd refers to an already-open file.
311 HashMessageID returns hashed message-id using MD5.
313
315 char *p;
316 char *Article;
317 char buff[256], errbuff[256];
318 FILE *F;
319 FILE *ToServer;
320 FILE *FromServer;
321 int port = 119;
322 if ((p = HeaderFind(Article, "From", 4)) == NULL)
324 Fatal("Can't find From line");
325 (void)strcpy(buff, p);
326 HeaderCleanFrom(buff);
327 if ((F = CAopen(FromServer, ToServer)) == NULL)
329 Fatal("Can't open active file");
330 /* Don't pass the file on to our children. */
332 CloseOnExec(fileno(F), 1);
333 /* Make a local copy. */
335 p = ReadInDescriptor(fileno(F), (struct stat *)NULL);
336 /* Close the file. */
338 CAclose();
339 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff) < 0)
341 Fatal("Can't connect to server");
342 if ((p = GetModeratorAddress("comp.sources.unix")) == NULL)
344 Fatal("Can't find moderator's address");
345
347 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. This is
348 revision 6124, dated 2003-01-14.
349
351 active(5), dbz(3z), parsedate(3), inn.conf(5), inndcomm(3), modera‐
352 tors(5), passwd.nntp(5).
353 LIBINN(3)