1NNTPClient(3)         User Contributed Perl Documentation        NNTPClient(3)
2
3
4

NAME

6       News::NNTPClient - Perl 5 module to talk to NNTP (RFC977) server
7

SYNOPSIS

9           use News::NNTPClient;
10
11           $c = new News::NNTPClient;
12           $c = new News::NNTPClient($server);
13           $c = new News::NNTPClient($server, $port);
14           $c = new News::NNTPClient($server, $port, $debug);
15

DESCRIPTION

17       This module implements a client interface to NNTP, enabling a Perl 5
18       application to talk to NNTP servers.  It uses the OOP (Object Oriented
19       Programming) interface introduced with Perl 5.
20
21       NNTPClient exports nothing.
22
23       A new NNTPClient object must be created with the new method.  Once this
24       has been done, all NNTP commands are accessed through this object.
25
26       Here are a couple of short examples.  The first prints all articles in
27       the "test" newsgroup:
28
29         #!/usr/local/bin/perl -w
30
31         use News::NNTPClient;
32
33         $c = new News::NNTPClient;
34
35         ($first, $last) = ($c->group("test"));
36
37         for (; $first <= $last; $first++) {
38             print $c->article($first);
39         }
40
41         __END__
42
43       This example prints the body of all articles in the "test" newsgroup
44       newer than one hour:
45
46         #!/usr/local/bin/perl -w
47
48         require News::NNTPClient;
49
50         $c = new News::NNTPClient;
51
52         foreach ($c->newnews("test", time - 3600)) {
53             print $c->body($_);
54         }
55
56         __END__
57
58   NNTPClient Commands
59       These commands are used to manipulate the NNTPClient object, and aren't
60       directly related to commands available on any NNTP server.
61
62       new       Use this to create a new NNTP connection. It takes three
63                 arguments, a hostname, a port and a debug flag.  It calls
64                 initialize.  Use an empty argument to specify defaults.
65
66                 If port is omitted or blank (""), looks for environment
67                 variable NNTPPORT, service "nntp", or uses 119.
68
69                 If host is omitted or empty (""), looks for environment
70                 variable NNTPSERVER or uses "news".
71
72                 Examples:
73
74                   $c = new News::NNTPClient;
75                 or
76                   $c = new News::NNTPClient("newsserver.some.where");
77                 or
78                   $c = new News::NNTPClient("experimental", 9999);
79                 or
80                   # Specify debug but use defaults.
81                   $c = new News::NNTPClient("", "", 2);
82
83                 Returns a blessed reference, representing a new NNTP
84                 connection.
85
86       initialize
87                 Calls port, host, connect, and response, in that order.  If
88                 any of these fail, initialization is aborted.
89
90       connect   Connects to current host/port.  Not normally needed, as the
91                 new method does this for you.  Closes any existing
92                 connection.  Sets the posting status.  See the postok method.
93
94       host      Sets the host that will be used on the next connect.  Not
95                 normally needed, as the new method does this for you.
96
97                 Without an argument, returns current host.
98
99                 Argument can be hostname or dotted quad, for example,
100                 "15.2.174.218".
101
102                 Returns fully qualified host name.
103
104       port      Sets the port that will be used on the next connect.  Not
105                 normally needed, as the new method does this for you.
106
107                 Without an argument, returns current port.
108
109                 Argument can be port number or name.  If it is a name, it
110                 must be a valid service.
111
112                 Returns port number.
113
114       debug     Sets the debug level.
115
116                 Without an argument, returns current debug level.
117
118                 There are currently three debug levels.  Level 0, level 1,
119                 and level 2.
120
121                 At level 0 the messages described for level 1 are not
122                 produced.  Debug level 0 is a way of turning off messages
123                 produced by the default debug level 1.  Serious error
124                 messages, such as EOF (End Of File) on the file handle, are
125                 still produced.
126
127                 At level 1, any NNTP command that results in a result code of
128                 400 or greater prints a warning message.  This is the
129                 default.
130
131                 At level 2, in addition to level 1 messages, status messages
132                 are printed to indicate actions taking place.
133
134                 Returns old debug value.
135
136       ok        Returns boolean status of most recent command.  NNTP return
137                 codes less than 400 are considered OK.  Not often needed as
138                 most commands return false upon failure anyway.
139
140       okprint   Returns boolean status of most recent command.  NNTP return
141                 codes less than 400 are considered OK.  Prints an error
142                 message for return codes of 400 or greater unless debug level
143                 is set to zero (0).
144
145                 This method is used internally by most commands, and could be
146                 considered to be "for internal use only".  You should use the
147                 return status of commands directly to determine pass-fail, or
148                 if needed the ok method can be used to check status later.
149
150       message   Returns the NNTP response message of the most recent command.
151
152                 Example, as returned by NNTP server version 1.5.11t:
153
154                   $c->slave;
155                   print $c->message;
156
157                   Kinky, kinky.  I don't support such perversions.
158
159       code      Returns the NNTP response code of the most recent command.
160
161                 Example:
162
163                   $c->article(1);
164                   print $c->code, "\n";
165
166                   412
167
168       postok    Returns the post-ability status that was reported upon
169                 connection or after the mode_reader command.
170
171       eol       Sets the End-Of-Line termination for text returned from the
172                 server.
173
174                 Returns the old EOL value.
175
176                 Default is \n.
177
178                 To set EOL to nothing, pass it the empty string.
179
180                 To query current EOL without setting it, call with no
181                 arguments.
182
183                 Example:
184
185                   $old_eol = $c->eol();     # Get original.
186                   $c->eol("");              # Set EOL to nothing.
187                   @article = $c->article(); # Fetch an article.
188                   $c->eol($old_eol);        # Restore value.
189
190       gmt       Sets GMT mode.  Returns old value.  To query GMT mode without
191                 setting it, call with no arguments.
192
193                 A true value means that GMT mode is used in the newgroups and
194                 newnews functions.  A false value means that local time is
195                 used.
196
197       fourdigityear
198                 Sets four digit year mode.  Returns old value.  To query four
199                 digit year mode without setting it, call with no arguments.
200
201                 A true value means that four digit years are used in the
202                 newgroups and newnews functions.  A false value means that an
203                 RFC977 compliant two digit year is used.
204
205                 This function is available for news servers that implemented
206                 four digit years rather than deal with non-y2k compliment two
207                 digit years.  RFC977 does not allow four digit years, and
208                 instead chooses the century closest.  I quote:
209
210                     The closest century is assumed as part of the year (i.e., 86
211                     specifies 1986, 30 specifies 2030, 99 is 1999, 00 is 2000).
212
213       version   Returns version number.
214
215                 This document represents @(#) $Revision: 0.37 $.
216
217   NNTP Commands
218       These commands directly correlate to NNTP server commands.  They return
219       a false value upon failure, true upon success.  The truth value is
220       usually some bit of useful information.  For example, the stat command
221       returns Message-ID if it is successful.
222
223       Some commands return multiple lines.  These lines are returned as an
224       array in array context, and as a reference to an array in scalar
225       context.  For example, if you do this:
226
227         @lines = $c->article(14);
228
229       then @lines will contain the article, one line per array element.
230       However, if you do this:
231
232         $lines = $c->article(14);
233
234       then $lines will contain a reference to an array.  This feature is for
235       those that don't like passing arrays from routine to routine.
236
237       mode_reader
238                 Some servers require this command to process NNTP client
239                 commands.  Sets postok status.  See postok.
240
241                 Returns OK status.
242
243       article   Retrieves an article from the server.  This is the main
244                 command for fetching articles.  Expects a single argument, an
245                 article number or Message-ID.  If you use an article number,
246                 you must be in a news group.  See group.
247
248                 Returns the header, a separating blank line, and the body of
249                 the article as an array of lines terminated by the current
250                 EOL.
251
252                 In scalar context a reference to the array is returned
253                 instead of the array itself.
254
255                 Examples:
256
257                   print $c->article('<art1234@soom.oom>');
258
259                   $c->group("test");
260
261                   print $c->article(99);
262
263       body      Expects a single argument, an article number or Message-ID.
264
265                 Returns the body of an article as an array of lines
266                 terminated by the current EOL.
267
268                 In scalar context a reference to the array is returned
269                 instead of the array itself.
270
271                 See article.
272
273       head      Expects a single argument, an article number or Message-ID.
274
275                 Returns the head of the article as an array of lines
276                 terminated by the current EOL.
277
278                 In scalar context a reference to the array is returned
279                 instead of the array itself.
280
281                 See article.
282
283       stat      Expects a single argument, an article number or Message-ID.
284
285                 The STAT command is like the ARTICLE command except that it
286                 does not return any text.  It can be used to set the "current
287                 article pointer" if passed an article number, or to validate
288                 a Message-ID if passed a Message-ID.
289
290                 Returns Message-ID if successful, otherwise returns false.
291
292       last      The "current article pointer" maintained by the server is
293                 moved to the previous article in the current news group.
294
295                 Returns Message-ID if successful, otherwise returns false.
296
297       next      The "current article pointer" maintained by the server is
298                 moved to the next article in the current news group.
299
300                 Returns Message-ID if successful, otherwise returns false.
301
302       group     Expects a single argument, the name of a valid news group.
303
304                 This command sets the current news group as maintained by the
305                 server.  It also sets the server maintained "current article
306                 pointer" to the first article in the group.  This enables the
307                 use of certain other server commands, such as article, head,
308                 body, stat, last, and next.  Also sets the current group in
309                 the NNTPClient object, which is used by the newnews and
310                 xindex commands.
311
312                 Returns (first, last) in list context, or "first-last" in
313                 scalar context, where first and last are the first and last
314                 article numbers as reported by the group command.  Returns
315                 false if there is an error.
316
317                 It is an error to attempt to select a non-existent news
318                 group.
319
320                 If the estimated article count is needed, it can be extracted
321                 from the message.  See message.
322
323       list      Accepts two optional arguments.  The first can be used
324                 indicate the type of list desired.  List type depends on
325                 server.  The second is a pattern that is use by some list
326                 types.
327
328                 Examples:
329
330                   print $c->list();
331                   print $c->list('active');
332                   print $c->list('active', 'local.*');
333                   print $c->list('newsgroups');
334
335                 With an argument of "active" or with no arguments, this
336                 command returns a list of valid newsgroups and associated
337                 information.  The format is:
338
339                   group last first p
340
341                 where group is the news group name, last is the article
342                 number of the last article, first is the article number of
343                 the first article, and p is flag indicating if posting is
344                 allowed.  A 'y' flag is an indication that posting is
345                 allowed.
346
347                 Other possible arguments are: newsgroups, distributions,
348                 subscriptions for B-News, and active.times, distributions,
349                 distrib.pats, newsgroups, overview.fmt for INN.
350
351                 Returns an array of lines terminated by the current EOL.
352
353                 In scalar context a reference to the array is returned
354                 instead of the array itself.
355
356       newgroups Expects at least one argument representing the date/time in
357                 seconds, or in "YYYYMMDD HHMMSS [GMT]" format.  The GMT part
358                 is optional.  If you wish to use GMT with the seconds format,
359                 first call gmt.  Remaining arguments are used as
360                 distributions.
361
362                 Example, print all new groups in the "comp" and/or "news"
363                 hierarchy as of one hour ago:
364
365                   print $c->newgroups(time() - 3600, "comp", "news");
366
367                 Returns list of new news group names as an array of lines
368                 terminated by the current EOL.
369
370                 In scalar context a reference to the array is returned
371                 instead of the array itself.
372
373       newnews   Expects one, two, or more arguments.
374
375                 If the first argument is a group name, it looks for new news
376                 in that group, and the date/time is the second argument.  If
377                 the first argument represents the date/time in seconds or in
378                 "YYYYMMDD HHMMSS [GMT]" format, then the group is is last
379                 group set via the group command. If no group command has been
380                 issued then the group is "*", representing all groups.  If
381                 you wish to use GMT in seconds format for the time, first
382                 call gmt.  Remaining arguments are use to restrict search to
383                 certain distribution(s).
384
385                 Returns a list of Message-IDs of articles that have been
386                 posted or received since the specified time.
387
388                 Examples:
389
390                   # Hour old news in news group "test".
391                   $c->newnews("test", time() - 3600);
392                 or
393                   # Hour old in all groups.
394                   $c->newnews(time() - 3600);
395                 or
396                   $c->newnews("*", time() - 3600);
397                 or
398                   # Hour old news in news group "test".
399                   $c->group("test");
400                   $c->newnews(time() - 3600);
401
402                 The group argument can include an asterisk "*" to specify a
403                 range news groups.  It can also include multiple news groups,
404                 separated by a comma ",".
405
406                 Example:
407
408                   $c->newnews("comp.*.sources,alt.sources", time() - 3600);
409
410                 An exclamation point "!" may be used to negate the selection
411                 of certain groups.
412
413                 Example:
414
415                   $c->newnews("*sources*,!*.d,!*.wanted", time() - 3600);
416
417                 Any additional distribution arguments will be concatenated
418                 together and send as a distribution list.  The distribution
419                 list will limit articles to those that have a Distribution:
420                 header containing one of the distributions passed.
421
422                 Example:
423
424                   $c->newnews("*", time() - 3600, "local", "na");
425
426                 Returns Message-IDs of new articles as an array of lines
427                 terminated by the current EOL.
428
429                 In scalar context a reference to the array is returned
430                 instead of the array itself.
431
432       help      Returns any server help information.  The format of the
433                 information is highly dependent on the server, but usually
434                 contains a list of NNTP commands recognized by the server.
435
436                 Returns an array of lines terminated by the current EOL.
437
438                 In scalar context a reference to the array is returned
439                 instead of the array itself.
440
441       post      Post an article.  Expects data to be posted as an array of
442                 lines.  Most servers expect, at a minimum, Newsgroups and
443                 Subject headers.  Be sure to separate the header from the
444                 body with a neck, er blank line.
445
446                 Example:
447
448                   @header = ("Newsgroups: test", "Subject: test", "From: tester");
449                   @body   = ("This is the body of the article");
450
451                   $c->post(@header, "", @body);
452
453                 There aren't really three arguments.  Perl folds all
454                 arguments into a single list.  You could also do this:
455
456                   @article = ("Newsgroups: test", "Subject: test", "From: tester", "", "Body");
457                   $c->post(@article);
458
459                 or even this:
460
461                   $c->post("Newsgroups: test", "Subject: test", "From: tester", "", "Body");
462
463                 Any "\n" characters at the end of a line will be trimmed.
464
465                 Returns status.
466
467       ihave     Transfer an article.  Expects an article Message-ID and the
468                 article to be sent as an array of lines.
469
470                 Example:
471
472                   # Fetch article from server on $c
473                   @article = $c->article($artid);
474
475                   # Send to server on $d
476                   if ($d->ihave($artid, @article)) {
477                       print "Article transfered\n";
478                   } else {
479                       print "Article rejected: ", $d->message, "\n";
480                   }
481
482       slave     Doesn't do anything on most servers.  Included for
483                 completeness.
484
485       DESTROY   This method is called whenever the the object created by
486                 News::NNTPClient::new is destroyed.  It calls quit to close
487                 the connection.
488
489       quit      Send the NNTP quit command and close the connection.  The
490                 connection can be then be re-opened with the connect method.
491                 Quit will automatically be called when the object is
492                 destroyed, so there is no need to explicitly call quit before
493                 exiting your program.
494
495   Extended NNTP Commands
496       These commands also directly correlate NNTP server commands, but are
497       not mentioned in RFC977, and are not part of the standard.  However,
498       many servers implement them, so they are included as part of this
499       package for your convenience.  If a command is not recognized by a
500       server, the server usually returns code 500, command unrecognized.
501
502       authinfo  Expects two arguments, user and password.
503
504       date      Returns server date in "YYYYMMDDhhmmss" format.
505
506       listgroup Expects one argument, a group name.  Default is current
507                 group.
508
509                 Returns article numbers as an array of lines terminated by
510                 the current EOL.
511
512                 In scalar context a reference to the array is returned
513                 instead of the array itself.
514
515       xmotd     Expects one argument of unix time in seconds or as a string
516                 in the form "YYYYMMDD HHMMSS".
517
518                 Returns the news servers "Message Of The Day" as an array of
519                 lines terminated by the current EOL.
520
521                 In scalar context a reference to the array is returned
522                 instead of the array itself.
523
524                 For example, the following will always print the message of
525                 the day, if there is any:
526
527                   print $c->xmotd(1);
528                   NNTP Server News2
529
530                   News administrator is Joseph Blough <joeblo@news.foo.com>
531
532       xgtitle   Expects one argument of a group pattern.  Default is current
533                 group.
534
535                 Returns group titles an array of lines terminated by the
536                 current EOL.
537
538                 In scalar context a reference to the array is returned
539                 instead of the array itself.
540
541                 Example:
542
543                   print $c->xgtitle("bit.listserv.v*");
544
545                   bit.listserv.valert-l   Virus Alert List. (Moderated)
546                   bit.listserv.vfort-l    VS-Fortran Discussion List.
547                   bit.listserv.vm-util    VM Utilities Discussion List.
548                   bit.listserv.vmesa-l    VM/ESA Mailing List.
549                   bit.listserv.vmslsv-l   VAX/VMS LISTSERV Discussion List.
550                   bit.listserv.vmxa-l     VM/XA Discussion List.
551                   bit.listserv.vnews-l    VNEWS Discussion List.
552                   bit.listserv.vpiej-l    Electronic Publishing Discussion
553
554       xpath     Expects one argument of an article Message-ID.  Returns the
555                 path name of the file on the server.
556
557                 Example:
558
559                   print print $c->xpath(q(<43bq5l$7b5@news.dtc.hp.com>))'
560                   hp/test/4469
561
562       xhdr      Fetch header for a range of articles.  First argument is name
563                 of header to fetch.  If omitted or blank, default to Message-
564                 ID.  Second argument is start of article range.  If omitted,
565                 defaults to 1.  Third argument is end of range.  If omitted,
566                 defaults to "".  The second argument can also be a Message-
567                 ID.
568
569                 Returns headers as an array of lines terminated by the
570                 current EOL.
571
572                 In scalar context a reference to the array is returned
573                 instead of the array itself.
574
575                 Examples:
576
577                   # Fetch Message-ID of article 1.
578                   $c->xhdr();
579
580                   # Fetch Subject of article 1.
581                   $c->xhdr("Subject");
582
583                   # Fetch Subject of article 3345.
584                   $c->xhdr("Subject", 3345);
585
586                   # Fetch Subjects of articles 3345-9873
587                   $c->xhdr("Subject", 3345, 9873);
588
589                   # Fetch Message-ID of articles 3345-9873
590                   $c->xhdr("", 3345,9873);
591
592                   # Fetch Subject for article with Message-ID
593                   $c->xhdr("Subject", '<797t0g$25f10@foo.com>');
594
595       xpat      Fetch header for a range of articles matching one or more
596                 patterns.  First argument is name of header to fetch.  If
597                 omitted or blank, default to Subject.  Second argument is
598                 start of article range.  If omitted, defaults to 1.  Next
599                 argument is end of range.  Remaining arguments are patterns
600                 to match.  Some servers use "*" for wildcard.
601
602                 Returns headers as an array of lines terminated by the
603                 current EOL.
604
605                 In scalar context a reference to the array is returned
606                 instead of the array itself.
607
608                 Examples:
609
610                   # Fetch Subject header of article 1.
611                   $c->xpat();
612
613                   # Fetch "From" header of article 1.
614                   $c->xpat("From");
615
616                   # Fetch "From" of article 3345.
617                   $c->xpat("From", 3345);
618
619                   # Fetch "From" of articles 3345-9873 matching *foo*
620                   $c->xpat("From", 3345, 9873, "*foo*");
621
622                   # Fetch "Subject" of articles 3345-9873 matching
623                   # *foo*, *bar*, *and*, *stuff*
624                   $c->xpat("", 3345,9873, qw(*foo* *bar* *and* *stuff*));
625
626       xover     Expects an article number or a starting and ending article
627                 number representing a range of articles.
628
629                 Returns overview information for each article as an array of
630                 lines terminated by the current EOL.
631
632                 In scalar context a reference to the array is returned
633                 instead of the array itself.
634
635                 Xover generally returns items separated by tabs.  Here is an
636                 example that prints out the xover fields from all messages in
637                 the "test" news group.
638
639                   #!/usr/local/bin/perl
640
641                   require News::NNTPClient;
642
643                   $c = new News::NNTPClient;
644
645                   @fields = qw(numb subj from date mesg refr char line xref);
646
647                   foreach $xover ($c->xover($c->group("test"))) {
648                       %fields = ();
649                       @fields{@fields} = split /\t/, $xover;
650                       print map { "$_: $fields{$_}\n" } @fields;
651                       print "\n";
652                   }
653
654                   __END__
655                                                 #
656                 =item I<xthread>
657
658                 Expects zero or one argument.  Value of argument doesn't
659                 matter.  If present, dbinit command is sent.  If absent,
660                 thread command is sent.
661
662                 Returns binary data as a scalar value.
663
664                 Format of data returned is unknown at this time.
665
666       xindex    Expects one argument, a group name.  If omitted, defaults to
667                 the group set by last group command.  If there hasn't been a
668                 group command, it returns an error;
669
670                 Returns index information for group as an array of lines
671                 terminated by the current EOL.
672
673                 In scalar context a reference to the array is returned
674                 instead of the array itself.
675
676       xsearch   Expects a query as an array of lines which are sent to the
677                 server, much like post.  Returns the result of the search as
678                 an array of lines or a reference to same.
679
680                 Format of query is unknown at this time.
681

AUTHOR

683       Rodger Anderson  <rodger@boi.hp.com>
684
686       Copyright 1995 Rodger Anderson. All rights reserved.  This module is
687       free software; you can redistribute it and/or modify it under the same
688       terms as Perl itself.
689
690
691
692perl v5.28.1                      2001-03-28                     NNTPClient(3)
Impressum