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
33 reference to an array with hosts to try in turn. The "host" method
34 will 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 containing 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
66 currently 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
70 message 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
89 filehandle 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
110 number of articles in the group, the number of the first article,
111 the 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
115 article 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
157 distribution pattern or a reference to a list of distribution
158 patterns. The result is the same as "list", but the groups return
159 will be limited to those created after "SINCE" and, if specified,
160 in one of 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
166 patterns.
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
174 current 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"
189 parameter, must be in the format as described by RFC822 and must
190 contain 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
209 documentation. Some servers may not support all of them.
210 newsgroups ( [ PATTERN ] )
212 Returns a reference to a hash where the keys are all the group
213 names which match "PATTERN", or all of the groups if no pattern is
214 specified, and each value contains the description text for the
215 group.
216 distributions ()
218 Returns a reference to a hash where the keys are all the possible
219 distribution names and the values are the distribution
220 descriptions.
221 subscriptions ()
223 Returns a reference to a list which contains a list of groups which
224 are recommended for a new user to subscribe to.
225 overview_fmt ()
227 Returns a reference to an array which contain the names of the
228 fields returned by "xover".
229 active_times ()
231 Returns a reference to a hash where the keys are the group names
232 and each value is a reference to an array containing the time the
233 groups was created and an identifier, possibly an Email address, of
234 the creator.
235 active ( [ PATTERN ] )
237 Similar to "list" but only active groups that match the pattern are
238 returned. "PATTERN" can be a group pattern.
239 xgtitle ( PATTERN )
241 Returns a reference to a hash where the keys are all the group
242 names which match "PATTERN" and each value is the description text
243 for the group.
244 xhdr ( HEADER, MESSAGE-SPEC )
246 Obtain the header field "HEADER" for all the messages specified.
247 The return value will be a reference to a hash where the keys are
249 the message numbers and each value contains the text of the
250 requested header for that message.
251 xover ( MESSAGE-SPEC )
253 The return value will be a reference to a hash where the keys are
254 the message numbers and each value contains a reference to an array
255 which contains the overview fields for that message.
256 The names of the fields can be obtained by calling "overview_fmt".
258 xpath ( MESSAGE-ID )
260 Returns the path name to the file on the server which contains the
261 specified message.
262 xpat ( HEADER, PATTERN, MESSAGE-SPEC)
264 The result is the same as "xhdr" except the is will be restricted
265 to headers where the text of the header matches "PATTERN"
266 xrover
268 The XROVER command returns reference information for the article(s)
269 specified.
270 Returns a reference to a HASH where the keys are the message
272 numbers and the values are the References: lines from the articles
273 listgroup ( [ GROUP ] )
275 Returns a reference to a list of all the active messages in
276 "GROUP", or the current group if "GROUP" is not specified.
277 reader
279 Tell the server that you are a reader and not another server.
280 This is required by some servers. For example if you are connecting
282 to an INN server and you have transfer permission your connection
283 will be connected to the transfer daemon, not the NNTP daemon.
284 Issuing this command will cause the transfer daemon to hand over
285 control to the NNTP daemon.
286 Some servers do not understand this command, but issuing it and
288 ignoring the response is harmless.
289
291 The following NNTP command are unsupported by the package, and there
292 are no plans to do so.
293 AUTHINFO GENERIC
295 XTHREAD
296 XSEARCH
297 XINDEX
298
300 MESSAGE-SPEC
301 "MESSAGE-SPEC" is either a single message-id, a single message
302 number, or a reference to a list of two message numbers.
303 If "MESSAGE-SPEC" is a reference to a list of two message numbers
305 and the second number in a range is less than or equal to the first
306 then the range represents all messages in the group after the first
307 message number.
308 NOTE For compatibility reasons only with earlier versions of
310 Net::NNTP a message spec can be passed as a list of two numbers,
311 this is deprecated and a reference to the list should now be passed
312 PATTERN
314 The "NNTP" protocol uses the "WILDMAT" format for patterns. The
315 WILDMAT format was first developed by Rich Salz based on the format
316 used in the UNIX "find" command to articulate file names. It was
317 developed to provide a uniform mechanism for matching patterns in
318 the same manner that the UNIX shell matches filenames.
319 Patterns are implicitly anchored at the beginning and end of each
321 string when testing for a match.
322 There are five pattern matching operations other than a strict one-
324 to-one match between the pattern and the source to be checked for a
325 match.
326 The first is an asterisk "*" to match any sequence of zero or more
328 characters.
329 The second is a question mark "?" to match any single character.
331 The third specifies a specific set of characters.
332 The set is specified as a list of characters, or as a range of
334 characters where the beginning and end of the range are separated
335 by a minus (or dash) character, or as any combination of lists and
336 ranges. The dash can also be included in the set as a character it
337 if is the beginning or end of the set. This set is enclosed in
338 square brackets. The close square bracket "]" may be used in a set
339 if it is the first character in the set.
340 The fourth operation is the same as the logical not of the third
342 operation and is specified the same way as the third with the
343 addition of a caret character "^" at the beginning of the test
344 string just inside the open square bracket.
345 The final operation uses the backslash character to invalidate the
347 special meaning of an open square bracket "[", the asterisk,
348 backslash or the question mark. Two backslashes in sequence will
349 result in the evaluation of the backslash as a character with no
350 special meaning.
351 Examples
353 "[^]-]"
354 matches any single character other than a close square bracket
355 or a minus sign/dash.
356 *bdc
358 matches any string that ends with the string "bdc" including
359 the string "bdc" (without quotes).
360 "[0-9a-zA-Z]"
362 matches any single printable alphanumeric ASCII character.
363 "a??d"
365 matches any four character string which begins with a and ends
366 with d.
367
369 Net::Cmd
370
372 Graham Barr <gbarr@pobox.com>
373
375 Copyright (c) 1995-1997 Graham Barr. All rights reserved. This program
376 is free software; you can redistribute it and/or modify it under the
377 same terms as Perl itself.
378perl v5.10.1 2009-02-12 Net::NNTP(3pm)