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 Class Methods
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 Object Methods
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, and
108 will change the current article pointer. $msgid is the message id
109 of an article as shown in that article's header. It is anticipated
110 that the client will obtain the $msgid from a list provided by the
111 "newnews" command, from references contained within another
112 article, or from the message-id provided in the response to some
113 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 array
169 and must be encoded by the caller to octets of whatever encoding is
170 required, e.g. by using the Encode module's "encode()" function.
171 "last()"
173 Set the "current article pointer" to the previous article in the
174 current newsgroup.
175 Returns the message-id of the article.
177 "date()"
179 Returns the date on the remote server. This date will be in a UNIX
180 time format (seconds since 1970)
181 "postok()"
183 "postok" will return true if the servers initial response indicated
184 that it will allow posting.
185 "authinfo($user, $pass)"
187 Authenticates to the server (using the original AUTHINFO USER /
188 AUTHINFO PASS form, defined in RFC2980) using the supplied username
189 and password. Please note that the password is sent in clear text
190 to the server. This command should not be used with valuable
191 passwords unless the connection to the server is somehow protected.
192 "authinfo_simple($user, $pass)"
194 Authenticates to the server (using the proposed NNTP V2 AUTHINFO
195 SIMPLE form, defined and deprecated in RFC2980) using the supplied
196 username and password. As with "authinfo" the password is sent in
197 clear text.
198 "list()"
200 Obtain information about all the active newsgroups. The results is
201 a reference to a hash where the key is a group name and each value
202 is a reference to an array. The elements in this array are:- the
203 last article number in the group, the first article number in the
204 group and any information flags about the group.
205 "newgroups($since[, $distributions])"
207 $since is a time value and $distributions is either a distribution
208 pattern or a reference to a list of distribution patterns. The
209 result is the same as "list", but the groups return will be limited
210 to those created after $since and, if specified, in one of the
211 distribution areas in $distributions.
212 "newnews($since[, $groups[, $distributions]])"
214 $since is a time value. $groups is either a group pattern or a
215 reference to a list of group patterns. $distributions is either a
216 distribution pattern or a reference to a list of distribution
217 patterns.
218 Returns a reference to a list which contains the message-ids of all
220 news posted after $since, that are in a groups which matched
221 $groups and a distribution which matches $distributions.
222 "next()"
224 Set the "current article pointer" to the next article in the
225 current newsgroup.
226 Returns the message-id of the article.
228 "post([$message])"
230 Post a new article to the news server. If $message is specified and
231 posting is allowed then the message will be sent.
232 If $message is not specified then the message must be sent using
234 the "datasend" and "dataend" methods from Net::Cmd
235 $message can be either an array of lines or a reference to an array
237 and must be encoded by the caller to octets of whatever encoding is
238 required, e.g. by using the Encode module's "encode()" function.
239 The message, either sent via "datasend" or as the $message
241 parameter, must be in the format as described by RFC822 and must
242 contain From:, Newsgroups: and Subject: headers.
243 "postfh()"
245 Post a new article to the news server using a tied filehandle. If
246 posting is allowed, this method will return a tied filehandle that
247 you can print() the contents of the article to be posted. You must
248 explicitly close() the filehandle when you are finished posting the
249 article, and the return value from the close() call will indicate
250 whether the message was successfully posted.
251 "slave()"
253 Tell the remote server that I am not a user client, but probably
254 another news server.
255 "quit()"
257 Quit the remote server and close the socket connection.
258 "can_inet6()"
260 Returns whether we can use IPv6.
261 "can_ssl()"
263 Returns whether we can use SSL.
264 Extension Methods
266 These methods use commands that are not part of the RFC977
267 documentation. Some servers may not support all of them.
268 "newsgroups([$pattern])"
270 Returns a reference to a hash where the keys are all the group
271 names which match $pattern, or all of the groups if no pattern is
272 specified, and each value contains the description text for the
273 group.
274 "distributions()"
276 Returns a reference to a hash where the keys are all the possible
277 distribution names and the values are the distribution
278 descriptions.
279 "distribution_patterns()"
281 Returns a reference to an array where each element, itself an array
282 reference, consists of the three fields of a line of the
283 distrib.pats list maintained by some NNTP servers, namely: a
284 weight, a wildmat and a value which the client may use to construct
285 a Distribution header.
286 "subscriptions()"
288 Returns a reference to a list which contains a list of groups which
289 are recommended for a new user to subscribe to.
290 "overview_fmt()"
292 Returns a reference to an array which contain the names of the
293 fields returned by "xover".
294 "active_times()"
296 Returns a reference to a hash where the keys are the group names
297 and each value is a reference to an array containing the time the
298 groups was created and an identifier, possibly an Email address, of
299 the creator.
300 "active([$pattern])"
302 Similar to "list" but only active groups that match the pattern are
303 returned. $pattern can be a group pattern.
304 "xgtitle($pattern)"
306 Returns a reference to a hash where the keys are all the group
307 names which match $pattern and each value is the description text
308 for the group.
309 "xhdr($header, $message_spec)"
311 Obtain the header field $header for all the messages specified.
312 The return value will be a reference to a hash where the keys are
314 the message numbers and each value contains the text of the
315 requested header for that message.
316 "xover($message_spec)"
318 The return value will be a reference to a hash where the keys are
319 the message numbers and each value contains a reference to an array
320 which contains the overview fields for that message.
321 The names of the fields can be obtained by calling "overview_fmt".
323 "xpath($message_id)"
325 Returns the path name to the file on the server which contains the
326 specified message.
327 "xpat($header, $pattern, $message_spec)"
329 The result is the same as "xhdr" except the is will be restricted
330 to headers where the text of the header matches $pattern
331 "xrover($message_spec)"
333 The XROVER command returns reference information for the article(s)
334 specified.
335 Returns a reference to a HASH where the keys are the message
337 numbers and the values are the References: lines from the articles
338 "listgroup([$group])"
340 Returns a reference to a list of all the active messages in $group,
341 or the current group if $group is not specified.
342 "reader()"
344 Tell the server that you are a reader and not another server.
345 This is required by some servers. For example if you are connecting
347 to an INN server and you have transfer permission your connection
348 will be connected to the transfer daemon, not the NNTP daemon.
349 Issuing this command will cause the transfer daemon to hand over
350 control to the NNTP daemon.
351 Some servers do not understand this command, but issuing it and
353 ignoring the response is harmless.
354 Unsupported
356 The following NNTP command are unsupported by the package, and there
357 are no plans to do so.
358 AUTHINFO GENERIC
360 XTHREAD
361 XSEARCH
362 XINDEX
363 Definitions
365 $message_spec
366 $message_spec is either a single message-id, a single message
367 number, or a reference to a list of two message numbers.
368 If $message_spec is a reference to a list of two message numbers
370 and the second number in a range is less than or equal to the first
371 then the range represents all messages in the group after the first
372 message number.
373 NOTE For compatibility reasons only with earlier versions of
375 Net::NNTP a message spec can be passed as a list of two numbers,
376 this is deprecated and a reference to the list should now be passed
377 $pattern
379 The "NNTP" protocol uses the "WILDMAT" format for patterns. The
380 WILDMAT format was first developed by Rich Salz based on the format
381 used in the UNIX "find" command to articulate file names. It was
382 developed to provide a uniform mechanism for matching patterns in
383 the same manner that the UNIX shell matches filenames.
384 Patterns are implicitly anchored at the beginning and end of each
386 string when testing for a match.
387 There are five pattern matching operations other than a strict one-
389 to-one match between the pattern and the source to be checked for a
390 match.
391 The first is an asterisk "*" to match any sequence of zero or more
393 characters.
394 The second is a question mark "?" to match any single character.
396 The third specifies a specific set of characters.
397 The set is specified as a list of characters, or as a range of
399 characters where the beginning and end of the range are separated
400 by a minus (or dash) character, or as any combination of lists and
401 ranges. The dash can also be included in the set as a character it
402 if is the beginning or end of the set. This set is enclosed in
403 square brackets. The close square bracket "]" may be used in a set
404 if it is the first character in the set.
405 The fourth operation is the same as the logical not of the third
407 operation and is specified the same way as the third with the
408 addition of a caret character "^" at the beginning of the test
409 string just inside the open square bracket.
410 The final operation uses the backslash character to invalidate the
412 special meaning of an open square bracket "[", the asterisk,
413 backslash or the question mark. Two backslashes in sequence will
414 result in the evaluation of the backslash as a character with no
415 special meaning.
416 Examples
418 "[^]-]"
419 matches any single character other than a close square bracket
420 or a minus sign/dash.
421 *bdc
423 matches any string that ends with the string "bdc" including
424 the string "bdc" (without quotes).
425 "[0-9a-zA-Z]"
427 matches any single printable alphanumeric ASCII character.
428 "a??d"
430 matches any four character string which begins with a and ends
431 with d.
432
434 None.
435
437 See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
438
440 Net::Cmd, IO::Socket::SSL.
441
443 Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
444 Steve Hay <shay@cpan.org <mailto:shay@cpan.org>> is now maintaining
446 libnet as of version 1.22_02.
447
449 Copyright (C) 1995-1997 Graham Barr. All rights reserved.
450 Copyright (C) 2013-2016, 2020 Steve Hay. All rights reserved.
452
454 This module is free software; you can redistribute it and/or modify it
455 under the same terms as Perl itself, i.e. under the terms of either the
456 GNU General Public License or the Artistic License, as specified in the
457 LICENCE file.
458
460 Version 3.13
461
463 23 Dec 2020
464
466 See the Changes file.
467perl v5.32.0 2021-01-04 Net::NNTP(3)