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