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

CONSTRUCTOR

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

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,
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
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
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
173       last ()
174           Set the "current article pointer" to the previous article in the
175           current newsgroup.
176
177           Returns the message-id of the article.
178
179       date ()
180           Returns the date on the remote server. This date will be in a UNIX
181           time format (seconds since 1970)
182
183       postok ()
184           "postok" will return true if the servers initial response indicated
185           that it will allow posting.
186
187       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
194       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
200       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
207       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
214       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
220           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
224       next ()
225           Set the "current article pointer" to the next article in the
226           current newsgroup.
227
228           Returns the message-id of the article.
229
230       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
234           If "MESSAGE" is not specified then the message must be sent using
235           the "datasend" and "dataend" methods from Net::Cmd
236
237           "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
242           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
246       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
254       slave ()
255           Tell the remote server that I am not a user client, but probably
256           another news server.
257
258       quit ()
259           Quit the remote server and close the socket connection.
260
261       can_inet6 ()
262           Returns whether we can use IPv6.
263
264       can_ssl ()
265           Returns whether we can use SSL.
266
267   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
271       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
277       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
282       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
289       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
293       overview_fmt ()
294           Returns a reference to an array which contain the names of the
295           fields returned by "xover".
296
297       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
303       active ( [ PATTERN ] )
304           Similar to "list" but only active groups that match the pattern are
305           returned.  "PATTERN" can be a group pattern.
306
307       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
312       xhdr ( HEADER, MESSAGE-SPEC )
313           Obtain the header field "HEADER" for all the messages specified.
314
315           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
319       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
324           The names of the fields can be obtained by calling "overview_fmt".
325
326       xpath ( MESSAGE-ID )
327           Returns the path name to the file on the server which contains the
328           specified message.
329
330       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
334       xrover ()
335           The XROVER command returns reference information for the article(s)
336           specified.
337
338           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
341       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
345       reader ()
346           Tell the server that you are a reader and not another server.
347
348           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
354           Some servers do not understand this command, but issuing it and
355           ignoring the response is harmless.
356

UNSUPPORTED

358       The following NNTP command are unsupported by the package, and there
359       are no plans to do so.
360
361           AUTHINFO GENERIC
362           XTHREAD
363           XSEARCH
364           XINDEX
365

DEFINITIONS

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
371           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
376           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
380       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
387           Patterns are implicitly anchored at the beginning and end of each
388           string when testing for a match.
389
390           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
394           The first is an asterisk "*" to match any sequence of zero or more
395           characters.
396
397           The second is a question mark "?" to match any single character.
398           The third specifies a specific set of characters.
399
400           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
408           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
413           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
419           Examples
420           "[^]-]"
421               matches any single character other than a close square bracket
422               or a minus sign/dash.
423
424           *bdc
425               matches any string that ends with the string "bdc" including
426               the string "bdc" (without quotes).
427
428           "[0-9a-zA-Z]"
429               matches any single printable alphanumeric ASCII character.
430
431           "a??d"
432               matches any four character string which begins with a and ends
433               with d.
434

SEE ALSO

436       Net::Cmd, IO::Socket::SSL
437

AUTHOR

439       Graham Barr <gbarr@pobox.com>.
440
441       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
447       Copyright (C) 2013-2016 Steve Hay.  All rights reserved.
448

LICENCE

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.
454
455
456
457perl v5.30.0                      2019-07-26                      Net::NNTP(3)
Impressum