1Net::NNTP(3) User Contributed Perl Documentation Net::NNTP(3)
2
6 Net::NNTP - NNTP Client class
7
9 use Net::NNTP;
10 $nntp = Net::NNTP->new("some.host.name");
12 $nntp->quit;
13 # start with SSL, e.g. nntps
15 $nntp = Net::NNTP->new("some.host.name", SSL => 1);
16 # start with plain and upgrade to SSL
18 $nntp = Net::NNTP->new("some.host.name");
19 $nntp->starttls;
20
22 "Net::NNTP" is a class implementing a simple NNTP client in Perl as
23 described in RFC977 and RFC4642. With IO::Socket::SSL installed it
24 also provides support for implicit and explicit TLS encryption, i.e.
25 NNTPS or NNTP+STARTTLS.
26 The Net::NNTP class is a subclass of Net::Cmd and (depending on
28 avaibility) of IO::Socket::IP, IO::Socket::INET6 or IO::Socket::INET.
29
31 new ( [ HOST ] [, OPTIONS ])
32 This is the constructor for a new Net::NNTP object. "HOST" is the
33 name of the remote host to which a NNTP connection is required. If
34 not given then it may be passed as the "Host" option described
35 below. If no host is passed then two environment variables are
36 checked, first "NNTPSERVER" then "NEWSHOST", then "Net::Config" is
37 checked, and if a host is not found then "news" is used.
38 "OPTIONS" are passed in a hash like fashion, using key and value
40 pairs. Possible options are:
41 Host - NNTP host to connect to. It may be a single scalar, as
43 defined for the "PeerAddr" option in IO::Socket::INET, or a
44 reference to an array with hosts to try in turn. The "host" method
45 will return the value which was used to connect to the host.
46 Port - port to connect to. Default - 119 for plain NNTP and 563
48 for immediate SSL (nntps).
49 SSL - If the connection should be done from start with SSL,
51 contrary to later upgrade with "starttls". You can use SSL
52 arguments as documented in IO::Socket::SSL, but it will usually use
53 the right arguments already.
54 Timeout - Maximum time, in seconds, to wait for a response from the
56 NNTP server, a value of zero will cause all IO operations to block.
57 (default: 120)
58 Debug - Enable the printing of debugging information to STDERR
60 Reader - If the remote server is INN then initially the connection
62 will be to innd, by default "Net::NNTP" will issue a "MODE READER"
63 command so that the remote server becomes nnrpd. If the "Reader"
64 option is given with a value of zero, then this command will not be
65 sent and the connection will be left talking to innd.
66 LocalAddr and LocalPort - These parameters are passed directly to
68 IO::Socket to allow binding the socket to a specific local address
69 and port.
70 Domain - This parameter is passed directly to IO::Socket and makes
72 it possible to enforce IPv4 connections even if IO::Socket::IP is
73 used as super class. Alternatively Family can be used.
74
76 Unless otherwise stated all methods return either a true or false
77 value, with true meaning that the operation was a success. When a
78 method states that it returns a value, failure will be returned as
79 undef or an empty list.
80 "Net::NNTP" inherits from "Net::Cmd" so methods defined in "Net::Cmd"
82 may be used to send commands to the remote NNTP server in addition to
83 the methods documented here.
84 host ()
86 Returns the value used by the constructor, and passed to
87 IO::Socket::INET, to connect to the host.
88 starttls ()
90 Upgrade existing plain connection to SSL. Any arguments necessary
91 for SSL must be given in "new" already.
92 article ( [ MSGID|MSGNUM ], [FH] )
94 Retrieve the header, a blank line, then the body (text) of the
95 specified article.
96 If "FH" is specified then it is expected to be a valid filehandle
98 and the result will be printed to it, on success a true value will
99 be returned. If "FH" is not specified then the return value, on
100 success, will be a reference to an array containing the article
101 requested, each entry in the array will contain one line of the
102 article.
103 If no arguments are passed then the current article in the
105 currently selected newsgroup is fetched.
106 "MSGNUM" is a numeric id of an article in the current newsgroup,
108 and will change the current article pointer. "MSGID" is the
109 message id of an article as shown in that article's header. It is
110 anticipated that the client will obtain the "MSGID" from a list
111 provided by the "newnews" command, from references contained within
112 another article, or from the message-id provided in the response to
113 some other commands.
114 If there is an error then "undef" will be returned.
116 body ( [ MSGID|MSGNUM ], [FH] )
118 Like "article" but only fetches the body of the article.
119 head ( [ MSGID|MSGNUM ], [FH] )
121 Like "article" but only fetches the headers for the article.
122 articlefh ( [ MSGID|MSGNUM ] )
124 bodyfh ( [ MSGID|MSGNUM ] )
125 headfh ( [ MSGID|MSGNUM ] )
126 These are similar to article(), body() and head(), but rather than
127 returning the requested data directly, they return a tied
128 filehandle from which to read the article.
129 nntpstat ( [ MSGID|MSGNUM ] )
131 The "nntpstat" command is similar to the "article" command except
132 that no text is returned. When selecting by message number within
133 a group, the "nntpstat" command serves to set the "current article
134 pointer" without sending text.
135 Using the "nntpstat" command to select by message-id is valid but
137 of questionable value, since a selection by message-id does not
138 alter the "current article pointer".
139 Returns the message-id of the "current article".
141 group ( [ GROUP ] )
143 Set and/or get the current group. If "GROUP" is not given then
144 information is returned on the current group.
145 In a scalar context it returns the group name.
147 In an array context the return value is a list containing, the
149 number of articles in the group, the number of the first article,
150 the number of the last article and the group name.
151 help ( )
153 Request help text (a short summary of commands that are understood
154 by this implementation) from the server. Returns the text or undef
155 upon failure.
156 ihave ( MSGID [, MESSAGE ])
158 The "ihave" command informs the server that the client has an
159 article whose id is "MSGID". If the server desires a copy of that
160 article and "MESSAGE" has been given then it will be sent.
161 Returns true if the server desires the article and "MESSAGE" was
163 successfully sent, if specified.
164 If "MESSAGE" is not specified then the message must be sent using
166 the "datasend" and "dataend" methods from Net::Cmd
167 "MESSAGE" can be either an array of lines or a reference to an
169 array and must be encoded by the caller to octets of whatever
170 encoding is required, e.g. by using the Encode module's "encode()"
171 function.
172 last ()
174 Set the "current article pointer" to the previous article in the
175 current newsgroup.
176 Returns the message-id of the article.
178 date ()
180 Returns the date on the remote server. This date will be in a UNIX
181 time format (seconds since 1970)
182 postok ()
184 "postok" will return true if the servers initial response indicated
185 that it will allow posting.
186 authinfo ( USER, PASS )
188 Authenticates to the server (using the original AUTHINFO USER /
189 AUTHINFO PASS form, defined in RFC2980) using the supplied username
190 and password. Please note that the password is sent in clear text
191 to the server. This command should not be used with valuable
192 passwords unless the connection to the server is somehow protected.
193 authinfo_simple ( USER, PASS )
195 Authenticates to the server (using the proposed NNTP V2 AUTHINFO
196 SIMPLE form, defined and deprecated in RFC2980) using the supplied
197 username and password. As with "authinfo" the password is sent in
198 clear text.
199 list ()
201 Obtain information about all the active newsgroups. The results is
202 a reference to a hash where the key is a group name and each value
203 is a reference to an array. The elements in this array are:- the
204 last article number in the group, the first article number in the
205 group and any information flags about the group.
206 newgroups ( SINCE [, DISTRIBUTIONS ])
208 "SINCE" is a time value and "DISTRIBUTIONS" is either a
209 distribution pattern or a reference to a list of distribution
210 patterns. The result is the same as "list", but the groups return
211 will be limited to those created after "SINCE" and, if specified,
212 in one of the distribution areas in "DISTRIBUTIONS".
213 newnews ( SINCE [, GROUPS [, DISTRIBUTIONS ]])
215 "SINCE" is a time value. "GROUPS" is either a group pattern or a
216 reference to a list of group patterns. "DISTRIBUTIONS" is either a
217 distribution pattern or a reference to a list of distribution
218 patterns.
219 Returns a reference to a list which contains the message-ids of all
221 news posted after "SINCE", that are in a groups which matched
222 "GROUPS" and a distribution which matches "DISTRIBUTIONS".
223 next ()
225 Set the "current article pointer" to the next article in the
226 current newsgroup.
227 Returns the message-id of the article.
229 post ( [ MESSAGE ] )
231 Post a new article to the news server. If "MESSAGE" is specified
232 and posting is allowed then the message will be sent.
233 If "MESSAGE" is not specified then the message must be sent using
235 the "datasend" and "dataend" methods from Net::Cmd
236 "MESSAGE" can be either an array of lines or a reference to an
238 array and must be encoded by the caller to octets of whatever
239 encoding is required, e.g. by using the Encode module's "encode()"
240 function.
241 The message, either sent via "datasend" or as the "MESSAGE"
243 parameter, must be in the format as described by RFC822 and must
244 contain From:, Newsgroups: and Subject: headers.
245 postfh ()
247 Post a new article to the news server using a tied filehandle. If
248 posting is allowed, this method will return a tied filehandle that
249 you can print() the contents of the article to be posted. You must
250 explicitly close() the filehandle when you are finished posting the
251 article, and the return value from the close() call will indicate
252 whether the message was successfully posted.
253 slave ()
255 Tell the remote server that I am not a user client, but probably
256 another news server.
257 quit ()
259 Quit the remote server and close the socket connection.
260 can_inet6 ()
262 Returns whether we can use IPv6.
263 can_ssl ()
265 Returns whether we can use SSL.
266 Extension methods
268 These methods use commands that are not part of the RFC977
269 documentation. Some servers may not support all of them.
270 newsgroups ( [ PATTERN ] )
272 Returns a reference to a hash where the keys are all the group
273 names which match "PATTERN", or all of the groups if no pattern is
274 specified, and each value contains the description text for the
275 group.
276 distributions ()
278 Returns a reference to a hash where the keys are all the possible
279 distribution names and the values are the distribution
280 descriptions.
281 distribution_patterns ()
283 Returns a reference to an array where each element, itself an array
284 reference, consists of the three fields of a line of the
285 distrib.pats list maintained by some NNTP servers, namely: a
286 weight, a wildmat and a value which the client may use to construct
287 a Distribution header.
288 subscriptions ()
290 Returns a reference to a list which contains a list of groups which
291 are recommended for a new user to subscribe to.
292 overview_fmt ()
294 Returns a reference to an array which contain the names of the
295 fields returned by "xover".
296 active_times ()
298 Returns a reference to a hash where the keys are the group names
299 and each value is a reference to an array containing the time the
300 groups was created and an identifier, possibly an Email address, of
301 the creator.
302 active ( [ PATTERN ] )
304 Similar to "list" but only active groups that match the pattern are
305 returned. "PATTERN" can be a group pattern.
306 xgtitle ( PATTERN )
308 Returns a reference to a hash where the keys are all the group
309 names which match "PATTERN" and each value is the description text
310 for the group.
311 xhdr ( HEADER, MESSAGE-SPEC )
313 Obtain the header field "HEADER" for all the messages specified.
314 The return value will be a reference to a hash where the keys are
316 the message numbers and each value contains the text of the
317 requested header for that message.
318 xover ( MESSAGE-SPEC )
320 The return value will be a reference to a hash where the keys are
321 the message numbers and each value contains a reference to an array
322 which contains the overview fields for that message.
323 The names of the fields can be obtained by calling "overview_fmt".
325 xpath ( MESSAGE-ID )
327 Returns the path name to the file on the server which contains the
328 specified message.
329 xpat ( HEADER, PATTERN, MESSAGE-SPEC)
331 The result is the same as "xhdr" except the is will be restricted
332 to headers where the text of the header matches "PATTERN"
333 xrover ()
335 The XROVER command returns reference information for the article(s)
336 specified.
337 Returns a reference to a HASH where the keys are the message
339 numbers and the values are the References: lines from the articles
340 listgroup ( [ GROUP ] )
342 Returns a reference to a list of all the active messages in
343 "GROUP", or the current group if "GROUP" is not specified.
344 reader ()
346 Tell the server that you are a reader and not another server.
347 This is required by some servers. For example if you are connecting
349 to an INN server and you have transfer permission your connection
350 will be connected to the transfer daemon, not the NNTP daemon.
351 Issuing this command will cause the transfer daemon to hand over
352 control to the NNTP daemon.
353 Some servers do not understand this command, but issuing it and
355 ignoring the response is harmless.
356
358 The following NNTP command are unsupported by the package, and there
359 are no plans to do so.
360 AUTHINFO GENERIC
362 XTHREAD
363 XSEARCH
364 XINDEX
365
367 MESSAGE-SPEC
368 "MESSAGE-SPEC" is either a single message-id, a single message
369 number, or a reference to a list of two message numbers.
370 If "MESSAGE-SPEC" is a reference to a list of two message numbers
372 and the second number in a range is less than or equal to the first
373 then the range represents all messages in the group after the first
374 message number.
375 NOTE For compatibility reasons only with earlier versions of
377 Net::NNTP a message spec can be passed as a list of two numbers,
378 this is deprecated and a reference to the list should now be passed
379 PATTERN
381 The "NNTP" protocol uses the "WILDMAT" format for patterns. The
382 WILDMAT format was first developed by Rich Salz based on the format
383 used in the UNIX "find" command to articulate file names. It was
384 developed to provide a uniform mechanism for matching patterns in
385 the same manner that the UNIX shell matches filenames.
386 Patterns are implicitly anchored at the beginning and end of each
388 string when testing for a match.
389 There are five pattern matching operations other than a strict one-
391 to-one match between the pattern and the source to be checked for a
392 match.
393 The first is an asterisk "*" to match any sequence of zero or more
395 characters.
396 The second is a question mark "?" to match any single character.
398 The third specifies a specific set of characters.
399 The set is specified as a list of characters, or as a range of
401 characters where the beginning and end of the range are separated
402 by a minus (or dash) character, or as any combination of lists and
403 ranges. The dash can also be included in the set as a character it
404 if is the beginning or end of the set. This set is enclosed in
405 square brackets. The close square bracket "]" may be used in a set
406 if it is the first character in the set.
407 The fourth operation is the same as the logical not of the third
409 operation and is specified the same way as the third with the
410 addition of a caret character "^" at the beginning of the test
411 string just inside the open square bracket.
412 The final operation uses the backslash character to invalidate the
414 special meaning of an open square bracket "[", the asterisk,
415 backslash or the question mark. Two backslashes in sequence will
416 result in the evaluation of the backslash as a character with no
417 special meaning.
418 Examples
420 "[^]-]"
421 matches any single character other than a close square bracket
422 or a minus sign/dash.
423 *bdc
425 matches any string that ends with the string "bdc" including
426 the string "bdc" (without quotes).
427 "[0-9a-zA-Z]"
429 matches any single printable alphanumeric ASCII character.
430 "a??d"
432 matches any four character string which begins with a and ends
433 with d.
434
436 Net::Cmd, IO::Socket::SSL
437
439 Graham Barr <gbarr@pobox.com>.
440 Steve Hay <shay@cpan.org> is now maintaining libnet as of version
442 1.22_02.
443
445 Copyright (C) 1995-1997 Graham Barr. All rights reserved.
446 Copyright (C) 2013-2016 Steve Hay. All rights reserved.
448
450 This module is free software; you can redistribute it and/or modify it
451 under the same terms as Perl itself, i.e. under the terms of either the
452 GNU General Public License or the Artistic License, as specified in the
453 LICENCE file.
454perl v5.30.0 2019-07-26 Net::NNTP(3)