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 /* Opening the active file on a client. */
21 extern FILE *CAopen(FILE *FromServer, FILE *ToServer);
22 extern FILE *CAlistopen(FILE *FromServer, FILE *ToServer,
23 const char *request);
24 extern void CAclose(void);
25 /* File locking. */
27 enum inn_locktype
28 {
29 INN_LOCK_READ,
30 INN_LOCK_WRITE,
31 INN_LOCK_UNLOCK
32 };
33 extern bool inn_lock_file(int fd, enum inn_locktype type,
35 bool block);
36 /* NNTP functions. */
38 extern int NNTPlocalopen(FILE **FromServerp, FILE **ToServerp,
39 char *errbuff, size_t len);
40 extern int NNTPremoteopen(int port, FILE **FromServerp,
41 FILE **ToServerp, char *errbuff,
42 size_t len);
43 extern int NNTPconnect(const char *host, int port,
44 FILE **FromServerp, FILE **ToServerp,
45 char *errbuff, size_t len);
46 extern int NNTPsendarticle(char *text, FILE *ToServer,
47 bool terminate);
48 extern int NNTPsendpassword(char *server, FILE *FromServer,
49 FILE *ToServer);
50 /* Hash functions. */
52 typedef struct {
53 char hash[16];
54 } HASH;
55 extern HASH HashMessageID(const char *MessageID);
57 /* Other useful functions. */
59 extern char *inn_getfqdn(const char *domain);
60 extern char *GetModeratorAddress(FILE *FromServer, FILE *ToServer,
61 char *group, char *moderatormailer);
62 /* Miscellaneous. */
64 extern int GetResourceUsage(double *usertime, double *systime);
65 extern void Radix32(unsigned long value, char *buff);
66 extern char *ReadInDescriptor(int fd, struct stat *Sbp);
67 extern char *ReadInFile(const char *name, struct stat *Sbp);
68 /* Setting or clearing file descriptor flags. */
70 #include "inn/fdflag.h"
71 bool fdflag_close_exec(int fd, bool flag);
73 bool fdflag_nonblocking(socket_type fd, bool flag);
74
76 libinn is a library of utility routines for manipulating Usenet
77 articles and related data. The whole documentation of libinn routines
78 is split into several specific man pages besides this one:
79 libinn_clientlib(3), libinn_dbz(3), libinn_inndcomm(3), libinn_list(3),
80 libinn_qio(3), libinn_tst(3) and libinn_uwildmat(3).
81 MACROS
83 "ISWHITE" is a macro which tests whether its char argument is a space
84 or a tabulation.
85 HEADERS-RELATED ROUTINES
87 GenerateMessageID uses the current time, process-ID, and fully
88 qualified domain name, which is passed as an argument and used if local
89 host cannot be resolved or is different from domain set in inn.conf, to
90 create a Message-ID header field that is highly likely to be unique.
91 The returned value points to static space that is reused on subsequent
92 calls.
93 HeaderCleanFrom removes the extraneous information from the value of a
95 From or Reply-To header field and leaves just the official mailing
96 address. In particular, the following transformations are made to the
97 from parameter:
98 • address --> address
100 • address (stuff) --> address
102 • stuff <address> --> address
104 The transformations are simple, based on RFC 5536 which limits the
106 format of the header field.
107 DDstart, DDcheck, and DDend are used to set the Distribution header
109 field; the "DD" stands for Default Distribution. The distrib.pats file
110 is consulted to determine the proper value for the Distribution header
111 field after all newsgroups have been checked. DDstart begins the
112 parsing. It returns a pointer to an opaque handle that should be used
113 on subsequent calls. The FromServer and ToServer parameters should be
114 "FILE"'s connected to the NNTP server for input and output,
115 respectively. If either parameter is NULL, then an empty default will
116 ultimately be returned if the file is not locally available.
117 DDcheck should be called with the handle, h, returned by DDstart and a
119 newsgroup, group, to check. It can be called as often as necessary.
120 DDend releases any state maintained in the handle and returns an
122 allocated copy of the text that should be used for the Distribution
123 header field.
124 CLIENT ACTIVE FILE
126 CAopen and CAclose provide news clients with access to the active file;
127 the "CA" stands for Client Active. CAopen opens the active file for
128 reading. It returns a pointer to an open "FILE", or NULL on error. If
129 a local or NFS-mounted copy exists, CAopen will use that file. The
130 FromServer and ToServer parameters should be "FILE"'s connected to the
131 NNTP server for input and output, respectively. See NNTPremoteopen or
132 NNTPlocalopen, below. If either parameter is NULL, then CAopen will
133 just return NULL if the file is not locally available. If they are not
134 NULL, CAopen will use them to query the NNTP server using the LIST
135 command to make a local temporary copy.
136 The CAlistopen sends a LIST command to the server and returns a
138 temporary file containing the results. The request parameter, if not
139 NULL, will be sent as an argument to the command. Unlike CAopen, this
140 routine will never use a locally-available copy of the active file.
141 CAclose closes the active file and removes any temporary file that
143 might have been created by CAopen or CAlistopen.
144 FILE LOCKING
146 inn_lock_file tries to lock the file descriptor fd. If block is true,
147 it will block until the lock can be made, otherwise it will return
148 false if the file cannot be locked. type is one of "INN_LOCK_READ",
149 "INN_LOCK_WRITE" or "INN_LOCK_UNLOCK". It returns false on failure or
150 true on success.
151 NNTP FUNCTIONS
153 NNTPlocalopen opens a connection to the private port of an InterNetNews
154 server running on the local host, if "HAVE_UNIX_DOMAIN_SOCKETS" in
155 include/config.h is defined. It returns "-1" on failure, or 0 on
156 success. FromServerp and ToServerp will be filled in with "FILE"'s
157 which can be used to communicate with the server. errbuff can either
158 be NULL or a pointer to a buffer at least 512 bytes long. If not NULL,
159 and the server refuses the connection, then it will be filled in with
160 the text of the server's reply. len should be the length of the
161 errbuff buffer. This routine is not for general use. If
162 "HAVE_UNIX_DOMAIN_SOCKETS" in include/config.h is not defined, this is
163 a stub routine, for compatibility with systems that have Unix-domain
164 stream sockets, and it then always returns "-1".
165 NNTPremoteopen does the same, except that it uses the server parameter
167 set in inn.conf as the local server, and opens a connection to the
168 port. Any client program can use this routine. It returns "-1" on
169 failure, or 0 on success.
170 NNTPconnect is the same as NNTPremoteopen except that the desired host
172 is given as the host parameter.
173 NNTPsendarticle writes text on ToServer using NNTP conventions for line
175 termination. The text should consist of one or more lines ending with
176 a newline. If terminate is true, then the routine will also write the
177 NNTP data-termination marker on the stream. It returns "-1" on
178 failure, or 0 on success.
179 NNTPsendpassword sends authentication information to an NNTP server by
181 finding the appropriate entry in the passwd.nntp file. server contains
182 the name of the host; the server parameter in inn.conf will be used if
183 server is NULL. FromServer and ToServer should be "FILE"'s that are
184 connected to the server. No action is taken if the specified host is
185 not listed in the password file.
186 HASHES
188 HashMessageID returns hashed Message-ID using MD5.
189 OTHER USEFUL FUNCTIONS
191 inn_getfqdn returns the fully qualified domain name of the local host.
192 domain is used to qualify the local host name if local host cannot be
193 resolved in DNS. The returned value points to newly-allocated memory
194 that the caller is responsible for freeing, or NULL on error.
195 GetModeratorAddress returns the mailing address of the moderator for
197 specified group or NULL on error. moderatormailer is used as its
198 address, if there is no matched moderator. See moderators(5) for
199 details on how the address is determined. GetModeratorAddress does no
200 checking to see if the specified group is actually moderated. The
201 returned value points to static space that is reused on subsequent
202 calls. The FromServer and ToServer parameters should be "FILE"'s
203 connected to the NNTP server for input and output, respectively. If
204 either of these parameters is NULL, then an attempt to get the list
205 from a local copy is made.
206 MISCELLANEOUS
208 GetResourceUsage fills in the usertime and systime parameters with the
209 total user and system time used by the current process and any children
210 it may have spawned. If "HAVE_GETRUSAGE" in include/config.h is
211 defined, it gets the values by doing a getrusage(2) system call;
212 otherwise it calls times(2). It returns "-1" on failure, or 0 on
213 success.
214 Radix32 converts the number in value into a radix-32 string into the
216 buffer pointed to by buff. The number is split into five-bit pieces
217 and each piece is converted into a character using the alphabet
218 "0..9a..v" to represent the numbers 0..32. Only the lowest 32 bits of
219 value are used, so buff needs only pointing to a buffer of eight bytes
220 (seven characters and the trailing "\0").
221 ReadInFile reads the file named name into allocated memory, appending a
223 terminating "\0" byte. It returns a pointer to the space, or NULL on
224 error. If Sbp is not NULL, it is taken as the address of a place to
225 store the results of a stat(2) call.
226 ReadInDescriptor performs the same function as ReadInFile except that
228 fd refers to an already-open file.
229 FILE DESCRIPTOR FLAGS
231 fdflag_close_exec can make a descriptor close-on-exec so that it is not
232 shared with any child processes. If the flag is true, the file is so
233 marked; if false, the close-on-exec mode is cleared. It returns false
234 on failure (or when the function is unsupported) or true on success.
235 fdflag_nonblocking enables (if flag is true) or disables (if flag is
237 false) non-blocking I/O on the indicated "socket_type" (which can be a
238 non-socket file descriptor on UNIX systems, but a "socket_type" is
239 expected on Windows). It returns false on failure or true on success.
240
242 #include "inn/fdflag.h"
243 #include "inn/libinn.h"
244 char *p;
246 char frombuff[256], errbuff[256];
247 FILE *F;
248 FILE *ToServer;
249 FILE *FromServer;
250 int port = 119;
251 strlcpy(frombuff, HDR(HDR__FROM), sizeof(frombuff));
253 HeaderCleanFrom(frombuff);
254 if ((F = CAopen(FromServer, ToServer)) == NULL)
256 Fatal("Can't open active file");
257 /* Don't pass the file on to our children. */
259 fdflag_close_exec(fileno(F), true);
260 /* Make a local copy. */
262 p = ReadInDescriptor(fileno(F), (struct stat *) NULL);
263 /* Close the file. */
265 CAclose();
266 if (NNTPremoteopen(port, &FromServer, &ToServer, errbuff,
268 sizeof(errbuff)) < 0)
269 Fatal("Can't connect to server");
270 if ((p = GetModeratorAddress(NULL, NULL, "comp.sources.unix",
272 "%s@example.com")) == NULL)
273 Fatal("Can't find moderator's address");
274
276 Written by Rich $alz <rsalz@uunet.uu.net> for InterNetNews. Rewritten
277 into POD by Julien Elie.
278
280 active(5), inn.conf(5), libinn_clientlib(3), libinn_dbz(3),
281 libinn_inndcomm(3), libinn_list(3), libinn_qio(3), libinn_tst(3),
282 libinn_uwildmat(3), moderators(5), passwd.nntp(5).
283INN 2.6.5 2022-02-18 libinn(3)