1Net::NNTP(3pm) Perl Programmers Reference Guide Net::NNTP(3pm)
2
6 Net::NNTP - NNTP Client class
7
9 use Net::NNTP;
10 $nntp = Net::NNTP->new("some.host.name");
12 $nntp->quit;
13
15 "Net::NNTP" is a class implementing a simple NNTP client in Perl as
16 described in RFC977. "Net::NNTP" inherits its communication methods
17 from "Net::Cmd"
18
20 new ( [ HOST ] [, OPTIONS ])
21 This is the constructor for a new Net::NNTP object. "HOST" is the
22 name of the remote host to which a NNTP connection is required. If
23 not given then it may be passed as the "Host" option described
24 below. If no host is passed then two environment variables are
25 checked, first "NNTPSERVER" then "NEWSHOST", then "Net::Config" is
26 checked, and if a host is not found then "news" is used.
27 "OPTIONS" are passed in a hash like fashion, using key and value
29 pairs. Possible options are:
30 Host - NNTP host to connect to. It may be a single scalar, as
32 defined for the "PeerAddr" option in IO::Socket::INET, or a refer‐
33 ence to an array with hosts to try in turn. The "host" method will
34 return the value which was used to connect to the host.
35 Timeout - Maximum time, in seconds, to wait for a response from the
37 NNTP server, a value of zero will cause all IO operations to block.
38 (default: 120)
39 Debug - Enable the printing of debugging information to STDERR
41 Reader - If the remote server is INN then initially the connection
43 will be to nnrpd, by default "Net::NNTP" will issue a "MODE READER"
44 command so that the remote server becomes innd. If the "Reader"
45 option is given with a value of zero, then this command will not be
46 sent and the connection will be left talking to nnrpd.
47
49 Unless otherwise stated all methods return either a true or false
50 value, with true meaning that the operation was a success. When a
51 method states that it returns a value, failure will be returned as
52 undef or an empty list.
53 article ( [ MSGID⎪MSGNUM ], [FH] )
55 Retrieve the header, a blank line, then the body (text) of the
56 specified article.
57 If "FH" is specified then it is expected to be a valid filehandle
59 and the result will be printed to it, on success a true value will
60 be returned. If "FH" is not specified then the return value, on
61 success, will be a reference to an array containg the article
62 requested, each entry in the array will contain one line of the
63 article.
64 If no arguments are passed then the current article in the cur‐
66 rently selected newsgroup is fetched.
67 "MSGNUM" is a numeric id of an article in the current newsgroup,
69 and will change the current article pointer. "MSGID" is the mes‐
70 sage id of an article as shown in that article's header. It is
71 anticipated that the client will obtain the "MSGID" from a list
72 provided by the "newnews" command, from references contained within
73 another article, or from the message-id provided in the response to
74 some other commands.
75 If there is an error then "undef" will be returned.
77 body ( [ MSGID⎪MSGNUM ], [FH] )
79 Like "article" but only fetches the body of the article.
80 head ( [ MSGID⎪MSGNUM ], [FH] )
82 Like "article" but only fetches the headers for the article.
83 articlefh ( [ MSGID⎪MSGNUM ] )
85 bodyfh ( [ MSGID⎪MSGNUM ] )
86 headfh ( [ MSGID⎪MSGNUM ] )
87 These are similar to article(), body() and head(), but rather than
88 returning the requested data directly, they return a tied filehan‐
89 dle from which to read the article.
90 nntpstat ( [ MSGID⎪MSGNUM ] )
92 The "nntpstat" command is similar to the "article" command except
93 that no text is returned. When selecting by message number within
94 a group, the "nntpstat" command serves to set the "current article
95 pointer" without sending text.
96 Using the "nntpstat" command to select by message-id is valid but
98 of questionable value, since a selection by message-id does not
99 alter the "current article pointer".
100 Returns the message-id of the "current article".
102 group ( [ GROUP ] )
104 Set and/or get the current group. If "GROUP" is not given then
105 information is returned on the current group.
106 In a scalar context it returns the group name.
108 In an array context the return value is a list containing, the num‐
110 ber of articles in the group, the number of the first article, the
111 number of the last article and the group name.
112 ihave ( MSGID [, MESSAGE ])
114 The "ihave" command informs the server that the client has an arti‐
115 cle whose id is "MSGID". If the server desires a copy of that
116 article, and "MESSAGE" has been given the it will be sent.
117 Returns true if the server desires the article and "MESSAGE" was
119 successfully sent,if specified.
120 If "MESSAGE" is not specified then the message must be sent using
122 the "datasend" and "dataend" methods from Net::Cmd
123 "MESSAGE" can be either an array of lines or a reference to an
125 array.
126 last ()
128 Set the "current article pointer" to the previous article in the
129 current newsgroup.
130 Returns the message-id of the article.
132 date ()
134 Returns the date on the remote server. This date will be in a UNIX
135 time format (seconds since 1970)
136 postok ()
138 "postok" will return true if the servers initial response indicated
139 that it will allow posting.
140 authinfo ( USER, PASS )
142 Authenticates to the server (using AUTHINFO USER / AUTHINFO PASS)
143 using the supplied username and password. Please note that the
144 password is sent in clear text to the server. This command should
145 not be used with valuable passwords unless the connection to the
146 server is somehow protected.
147 list ()
149 Obtain information about all the active newsgroups. The results is
150 a reference to a hash where the key is a group name and each value
151 is a reference to an array. The elements in this array are:- the
152 last article number in the group, the first article number in the
153 group and any information flags about the group.
154 newgroups ( SINCE [, DISTRIBUTIONS ])
156 "SINCE" is a time value and "DISTRIBUTIONS" is either a distribu‐
157 tion pattern or a reference to a list of distribution patterns.
158 The result is the same as "list", but the groups return will be
159 limited to those created after "SINCE" and, if specified, in one of
160 the distribution areas in "DISTRIBUTIONS".
161 newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])
163 "SINCE" is a time value. "GROUPS" is either a group pattern or a
164 reference to a list of group patterns. "DISTRIBUTIONS" is either a
165 distribution pattern or a reference to a list of distribution pat‐
166 terns.
167 Returns a reference to a list which contains the message-ids of all
169 news posted after "SINCE", that are in a groups which matched
170 "GROUPS" and a distribution which matches "DISTRIBUTIONS".
171 next ()
173 Set the "current article pointer" to the next article in the cur‐
174 rent newsgroup.
175 Returns the message-id of the article.
177 post ( [ MESSAGE ] )
179 Post a new article to the news server. If "MESSAGE" is specified
180 and posting is allowed then the message will be sent.
181 If "MESSAGE" is not specified then the message must be sent using
183 the "datasend" and "dataend" methods from Net::Cmd
184 "MESSAGE" can be either an array of lines or a reference to an
186 array.
187 The message, either sent via "datasend" or as the "MESSAGE" parame‐
189 ter, must be in the format as described by RFC822 and must contain
190 From:, Newsgroups: and Subject: headers.
191 postfh ()
193 Post a new article to the news server using a tied filehandle. If
194 posting is allowed, this method will return a tied filehandle that
195 you can print() the contents of the article to be posted. You must
196 explicitly close() the filehandle when you are finished posting the
197 article, and the return value from the close() call will indicate
198 whether the message was successfully posted.
199 slave ()
201 Tell the remote server that I am not a user client, but probably
202 another news server.
203 quit ()
205 Quit the remote server and close the socket connection.
206 Extension methods
208 These methods use commands that are not part of the RFC977 documenta‐
210 tion. Some servers may not support all of them.
211 newsgroups ( [ PATTERN ] )
213 Returns a reference to a hash where the keys are all the group
214 names which match "PATTERN", or all of the groups if no pattern is
215 specified, and each value contains the description text for the
216 group.
217 distributions ()
219 Returns a reference to a hash where the keys are all the possible
220 distribution names and the values are the distribution descrip‐
221 tions.
222 subscriptions ()
224 Returns a reference to a list which contains a list of groups which
225 are recommended for a new user to subscribe to.
226 overview_fmt ()
228 Returns a reference to an array which contain the names of the
229 fields returned by "xover".
230 active_times ()
232 Returns a reference to a hash where the keys are the group names
233 and each value is a reference to an array containing the time the
234 groups was created and an identifier, possibly an Email address, of
235 the creator.
236 active ( [ PATTERN ] )
238 Similar to "list" but only active groups that match the pattern are
239 returned. "PATTERN" can be a group pattern.
240 xgtitle ( PATTERN )
242 Returns a reference to a hash where the keys are all the group
243 names which match "PATTERN" and each value is the description text
244 for the group.
245 xhdr ( HEADER, MESSAGE-SPEC )
247 Obtain the header field "HEADER" for all the messages specified.
248 The return value will be a reference to a hash where the keys are
250 the message numbers and each value contains the text of the
251 requested header for that message.
252 xover ( MESSAGE-SPEC )
254 The return value will be a reference to a hash where the keys are
255 the message numbers and each value contains a reference to an array
256 which contains the overview fields for that message.
257 The names of the fields can be obtained by calling "overview_fmt".
259 xpath ( MESSAGE-ID )
261 Returns the path name to the file on the server which contains the
262 specified message.
263 xpat ( HEADER, PATTERN, MESSAGE-SPEC)
265 The result is the same as "xhdr" except the is will be restricted
266 to headers where the text of the header matches "PATTERN"
267 xrover
269 The XROVER command returns reference information for the article(s)
270 specified.
271 Returns a reference to a HASH where the keys are the message num‐
273 bers and the values are the References: lines from the articles
274 listgroup ( [ GROUP ] )
276 Returns a reference to a list of all the active messages in
277 "GROUP", or the current group if "GROUP" is not specified.
278 reader
280 Tell the server that you are a reader and not another server.
281 This is required by some servers. For example if you are connecting
283 to an INN server and you have transfer permission your connection
284 will be connected to the transfer daemon, not the NNTP daemon.
285 Issuing this command will cause the transfer daemon to hand over
286 control to the NNTP daemon.
287 Some servers do not understand this command, but issuing it and
289 ignoring the response is harmless.
290
292 The following NNTP command are unsupported by the package, and there
293 are no plans to do so.
294 AUTHINFO GENERIC
296 XTHREAD
297 XSEARCH
298 XINDEX
299
301 MESSAGE-SPEC
302 "MESSAGE-SPEC" is either a single message-id, a single message num‐
303 ber, or a reference to a list of two message numbers.
304 If "MESSAGE-SPEC" is a reference to a list of two message numbers
306 and the second number in a range is less than or equal to the first
307 then the range represents all messages in the group after the first
308 message number.
309 NOTE For compatibility reasons only with earlier versions of
311 Net::NNTP a message spec can be passed as a list of two numbers,
312 this is deprecated and a reference to the list should now be passed
313 PATTERN
315 The "NNTP" protocol uses the "WILDMAT" format for patterns. The
316 WILDMAT format was first developed by Rich Salz based on the format
317 used in the UNIX "find" command to articulate file names. It was
318 developed to provide a uniform mechanism for matching patterns in
319 the same manner that the UNIX shell matches filenames.
320 Patterns are implicitly anchored at the beginning and end of each
322 string when testing for a match.
323 There are five pattern matching operations other than a strict one-
325 to-one match between the pattern and the source to be checked for a
326 match.
327 The first is an asterisk "*" to match any sequence of zero or more
329 characters.
330 The second is a question mark "?" to match any single character.
332 The third specifies a specific set of characters.
333 The set is specified as a list of characters, or as a range of
335 characters where the beginning and end of the range are separated
336 by a minus (or dash) character, or as any combination of lists and
337 ranges. The dash can also be included in the set as a character it
338 if is the beginning or end of the set. This set is enclosed in
339 square brackets. The close square bracket "]" may be used in a set
340 if it is the first character in the set.
341 The fourth operation is the same as the logical not of the third
343 operation and is specified the same way as the third with the addi‐
344 tion of a caret character "^" at the beginning of the test string
345 just inside the open square bracket.
346 The final operation uses the backslash character to invalidate the
348 special meaning of an open square bracket "[", the asterisk, back‐
349 slash or the question mark. Two backslashes in sequence will result
350 in the evaluation of the backslash as a character with no special
351 meaning.
352 Examples
354 "[^]-]"
355 matches any single character other than a close square bracket
356 or a minus sign/dash.
357 *bdc
359 matches any string that ends with the string "bdc" including
360 the string "bdc" (without quotes).
361 "[0-9a-zA-Z]"
363 matches any single printable alphanumeric ASCII character.
364 "a??d"
366 matches any four character string which begins with a and ends
367 with d.
368
370 Net::Cmd
371
373 Graham Barr <gbarr@pobox.com>
374
376 Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program
377 is free software; you can redistribute it and/or modify it under the
378 same terms as Perl itself.
379 $Id: //depot/libnet/Net/NNTP.pm#18 $
381perl v5.8.8 2001-09-21 Net::NNTP(3pm)