1Net::NNTP(3)          User Contributed Perl Documentation         Net::NNTP(3)
2
3
4

NAME

6       Net::NNTP - NNTP Client class
7

SYNOPSIS

9           use Net::NNTP;
10
11           $nntp = Net::NNTP->new("some.host.name");
12           $nntp->quit;
13
14           # start with SSL, e.g. nntps
15           $nntp = Net::NNTP->new("some.host.name", SSL => 1);
16
17           # start with plain and upgrade to SSL
18           $nntp = Net::NNTP->new("some.host.name");
19           $nntp->starttls;
20

DESCRIPTION

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
27       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
30   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
39           %options are passed in a hash like fashion, using key and value
40           pairs.  Possible options are:
41
42           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
47           Port - port to connect to.  Default - 119 for plain NNTP and 563
48           for immediate SSL (nntps).
49
50           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
55           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
59           Debug - Enable the printing of debugging information to STDERR
60
61           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
67           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
71           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
75   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
81       "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
85       "host()"
86           Returns the value used by the constructor, and passed to
87           IO::Socket::INET, to connect to the host.
88
89       "starttls()"
90           Upgrade existing plain connection to SSL.  Any arguments necessary
91           for SSL must be given in "new" already.
92
93       "article([{$msgid|$msgnum}[, $fh]])"
94           Retrieve the header, a blank line, then the body (text) of the
95           specified article.
96
97           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
104           If no arguments are passed then the current article in the
105           currently selected newsgroup is fetched.
106
107           $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
115           If there is an error then "undef" will be returned.
116
117       "body([{$msgid|$msgnum}[, [$fh]])"
118           Like "article" but only fetches the body of the article.
119
120       "head([{$msgid|$msgnum}[, [$fh]])"
121           Like "article" but only fetches the headers for the article.
122
123       "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
130       "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
136           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
140           Returns the message-id of the "current article".
141
142       "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
146           In a scalar context it returns the group name.
147
148           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
152       "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
157       "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
162           Returns true if the server desires the article and $message was
163           successfully sent, if specified.
164
165           If $message is not specified then the message must be sent using
166           the "datasend" and "dataend" methods from Net::Cmd
167
168           $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
172       "last()"
173           Set the "current article pointer" to the previous article in the
174           current newsgroup.
175
176           Returns the message-id of the article.
177
178       "date()"
179           Returns the date on the remote server. This date will be in a UNIX
180           time format (seconds since 1970)
181
182       "postok()"
183           "postok" will return true if the servers initial response indicated
184           that it will allow posting.
185
186       "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
193       "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
199       "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
206       "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
213       "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
219           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
223       "next()"
224           Set the "current article pointer" to the next article in the
225           current newsgroup.
226
227           Returns the message-id of the article.
228
229       "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
233           If $message is not specified then the message must be sent using
234           the "datasend" and "dataend" methods from Net::Cmd
235
236           $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
240           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
244       "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
252       "slave()"
253           Tell the remote server that I am not a user client, but probably
254           another news server.
255
256       "quit()"
257           Quit the remote server and close the socket connection.
258
259       "can_inet6()"
260           Returns whether we can use IPv6.
261
262       "can_ssl()"
263           Returns whether we can use SSL.
264
265   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
269       "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
275       "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
280       "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
287       "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
291       "overview_fmt()"
292           Returns a reference to an array which contain the names of the
293           fields returned by "xover".
294
295       "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
301       "active([$pattern])"
302           Similar to "list" but only active groups that match the pattern are
303           returned.  $pattern can be a group pattern.
304
305       "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
310       "xhdr($header, $message_spec)"
311           Obtain the header field $header for all the messages specified.
312
313           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
317       "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
322           The names of the fields can be obtained by calling "overview_fmt".
323
324       "xpath($message_id)"
325           Returns the path name to the file on the server which contains the
326           specified message.
327
328       "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
332       "xrover($message_spec)"
333           The XROVER command returns reference information for the article(s)
334           specified.
335
336           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
339       "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
343       "reader()"
344           Tell the server that you are a reader and not another server.
345
346           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
352           Some servers do not understand this command, but issuing it and
353           ignoring the response is harmless.
354
355   Unsupported
356       The following NNTP command are unsupported by the package, and there
357       are no plans to do so.
358
359           AUTHINFO GENERIC
360           XTHREAD
361           XSEARCH
362           XINDEX
363
364   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
369           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
374           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
378       $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
385           Patterns are implicitly anchored at the beginning and end of each
386           string when testing for a match.
387
388           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
392           The first is an asterisk "*" to match any sequence of zero or more
393           characters.
394
395           The second is a question mark "?" to match any single character.
396           The third specifies a specific set of characters.
397
398           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
406           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
411           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
417           Examples
418           "[^]-]"
419               matches any single character other than a close square bracket
420               or a minus sign/dash.
421
422           *bdc
423               matches any string that ends with the string "bdc" including
424               the string "bdc" (without quotes).
425
426           "[0-9a-zA-Z]"
427               matches any single printable alphanumeric ASCII character.
428
429           "a??d"
430               matches any four character string which begins with a and ends
431               with d.
432

EXPORTS

434       None.
435

KNOWN BUGS

437       See <https://rt.cpan.org/Dist/Display.html?Status=Active&Queue=libnet>.
438

SEE ALSO

440       Net::Cmd, IO::Socket::SSL.
441

AUTHOR

443       Graham Barr <gbarr@pobox.com <mailto:gbarr@pobox.com>>.
444
445       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
451       Copyright (C) 2013-2016, 2020 Steve Hay.  All rights reserved.
452

LICENCE

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

VERSION

460       Version 3.13
461

DATE

463       23 Dec 2020
464

HISTORY

466       See the Changes file.
467
468
469
470perl v5.34.0                      2021-07-27                      Net::NNTP(3)
Impressum