1NNTPClient(3) User Contributed Perl Documentation NNTPClient(3)
2
6 News::NNTPClient - Perl 5 module to talk to NNTP (RFC977) server
7
9 use News::NNTPClient;
10 $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
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 NNTPClient exports nothing.
22 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 Here are a couple of short examples. The first prints all articles in
27 the "test" newsgroup:
28 #!/usr/local/bin/perl -w
30 use News::NNTPClient;
32 $c = new News::NNTPClient;
34 ($first, $last) = ($c->group("test"));
36 for (; $first <= $last; $first++) {
38 print $c->article($first);
39 }
40 __END__
42 This example prints the body of all articles in the "test" newsgroup
44 newer than one hour:
45 #!/usr/local/bin/perl -w
47 require News::NNTPClient;
49 $c = new News::NNTPClient;
51 foreach ($c->newnews("test", time - 3600)) {
53 print $c->body($_);
54 }
55 __END__
57 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 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 If port is omitted or blank (""), looks for environment
67 variable NNTPPORT, service "nntp", or uses 119.
68 If host is omitted or empty (""), looks for environment
70 variable NNTPSERVER or uses "news".
71 Examples:
73 $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 Returns a blessed reference, representing a new NNTP
84 connection.
85 initialize
87 Calls port, host, connect, and response, in that order. If
88 any of these fail, initialization is aborted.
89 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 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 Without an argument, returns current host.
98 Argument can be hostname or dotted quad, for example,
100 "15.2.174.218".
101 Returns fully qualified host name.
103 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 Without an argument, returns current port.
108 Argument can be port number or name. If it is a name, it
110 must be a valid service.
111 Returns port number.
113 debug Sets the debug level.
115 Without an argument, returns current debug level.
117 There are currently three debug levels. Level 0, level 1,
119 and level 2.
120 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 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 At level 2, in addition to level 1 messages, status messages
132 are printed to indicate actions taking place.
133 Returns old debug value.
135 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 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 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 message Returns the NNTP response message of the most recent command.
151 Example, as returned by NNTP server version 1.5.11t:
153 $c->slave;
155 print $c->message;
156 Kinky, kinky. I don't support such perversions.
158 code Returns the NNTP response code of the most recent command.
160 Example:
162 $c->article(1);
164 print $c->code, "\n";
165 412
167 postok Returns the post-ability status that was reported upon
169 connection or after the mode_reader command.
170 eol Sets the End-Of-Line termination for text returned from the
172 server.
173 Returns the old EOL value.
175 Default is \n.
177 To set EOL to nothing, pass it the empty string.
179 To query current EOL without setting it, call with no
181 arguments.
182 Example:
184 $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 gmt Sets GMT mode. Returns old value. To query GMT mode without
191 setting it, call with no arguments.
192 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 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 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 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 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 version Returns version number.
214 This document represents @(#) $Revision: 0.37 $.
216 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 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 @lines = $c->article(14);
228 then @lines will contain the article, one line per array element.
230 However, if you do this:
231 $lines = $c->article(14);
233 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 mode_reader
238 Some servers require this command to process NNTP client
239 commands. Sets postok status. See postok.
240 Returns OK status.
242 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 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 In scalar context a reference to the array is returned
253 instead of the array itself.
254 Examples:
256 print $c->article('<art1234@soom.oom>');
258 $c->group("test");
260 print $c->article(99);
262 body Expects a single argument, an article number or Message-ID.
264 Returns the body of an article as an array of lines
266 terminated by the current EOL.
267 In scalar context a reference to the array is returned
269 instead of the array itself.
270 See article.
272 head Expects a single argument, an article number or Message-ID.
274 Returns the head of the article as an array of lines
276 terminated by the current EOL.
277 In scalar context a reference to the array is returned
279 instead of the array itself.
280 See article.
282 stat Expects a single argument, an article number or Message-ID.
284 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 Returns Message-ID if successful, otherwise returns false.
291 last The "current article pointer" maintained by the server is
293 moved to the previous article in the current news group.
294 Returns Message-ID if successful, otherwise returns false.
296 next The "current article pointer" maintained by the server is
298 moved to the next article in the current news group.
299 Returns Message-ID if successful, otherwise returns false.
301 group Expects a single argument, the name of a valid news group.
303 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 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 It is an error to attempt to select a non-existent news
318 group.
319 If the estimated article count is needed, it can be extracted
321 from the message. See message.
322 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 Examples:
329 print $c->list();
331 print $c->list('active');
332 print $c->list('active', 'local.*');
333 print $c->list('newsgroups');
334 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 group last first p
340 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 Other possible arguments are: newsgroups, distributions,
348 subscriptions for B-News, and active.times, distributions,
349 distrib.pats, newsgroups, overview.fmt for INN.
350 Returns an array of lines terminated by the current EOL.
352 In scalar context a reference to the array is returned
354 instead of the array itself.
355 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 Example, print all new groups in the "comp" and/or "news"
363 hierarchy as of one hour ago:
364 print $c->newgroups(time() - 3600, "comp", "news");
366 Returns list of new news group names as an array of lines
368 terminated by the current EOL.
369 In scalar context a reference to the array is returned
371 instead of the array itself.
372 newnews Expects one, two, or more arguments.
374 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 Returns a list of Message-IDs of articles that have been
386 posted or received since the specified time.
387 Examples:
389 # 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 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 Example:
407 $c->newnews("comp.*.sources,alt.sources", time() - 3600);
409 An exclamation point "!" may be used to negate the selection
411 of certain groups.
412 Example:
414 $c->newnews("*sources*,!*.d,!*.wanted", time() - 3600);
416 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 Example:
423 $c->newnews("*", time() - 3600, "local", "na");
425 Returns Message-IDs of new articles as an array of lines
427 terminated by the current EOL.
428 In scalar context a reference to the array is returned
430 instead of the array itself.
431 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 Returns an array of lines terminated by the current EOL.
437 In scalar context a reference to the array is returned
439 instead of the array itself.
440 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 Example:
447 @header = ("Newsgroups: test", "Subject: test", "From: tester");
449 @body = ("This is the body of the article");
450 $c->post(@header, "", @body);
452 There aren't really three arguments. Perl folds all
454 arguments into a single list. You could also do this:
455 @article = ("Newsgroups: test", "Subject: test", "From: tester", "", "Body");
457 $c->post(@article);
458 or even this:
460 $c->post("Newsgroups: test", "Subject: test", "From: tester", "", "Body");
462 Any "\n" characters at the end of a line will be trimmed.
464 Returns status.
466 ihave Transfer an article. Expects an article Message-ID and the
468 article to be sent as an array of lines.
469 Example:
471 # Fetch article from server on $c
473 @article = $c->article($artid);
474 # 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 slave Doesn't do anything on most servers. Included for
483 completeness.
484 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 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 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 authinfo Expects two arguments, user and password.
503 date Returns server date in "YYYYMMDDhhmmss" format.
505 listgroup Expects one argument, a group name. Default is current
507 group.
508 Returns article numbers as an array of lines terminated by
510 the current EOL.
511 In scalar context a reference to the array is returned
513 instead of the array itself.
514 xmotd Expects one argument of unix time in seconds or as a string
516 in the form "YYYYMMDD HHMMSS".
517 Returns the news servers "Message Of The Day" as an array of
519 lines terminated by the current EOL.
520 In scalar context a reference to the array is returned
522 instead of the array itself.
523 For example, the following will always print the message of
525 the day, if there is any:
526 print $c->xmotd(1);
528 NNTP Server News2
529 News administrator is Joseph Blough <joeblo@news.foo.com>
531 xgtitle Expects one argument of a group pattern. Default is current
533 group.
534 Returns group titles an array of lines terminated by the
536 current EOL.
537 In scalar context a reference to the array is returned
539 instead of the array itself.
540 Example:
542 print $c->xgtitle("bit.listserv.v*");
544 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 xpath Expects one argument of an article Message-ID. Returns the
555 path name of the file on the server.
556 Example:
558 print print $c->xpath(q(<43bq5l$7b5@news.dtc.hp.com>))'
560 hp/test/4469
561 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 Returns headers as an array of lines terminated by the
570 current EOL.
571 In scalar context a reference to the array is returned
573 instead of the array itself.
574 Examples:
576 # Fetch Message-ID of article 1.
578 $c->xhdr();
579 # Fetch Subject of article 1.
581 $c->xhdr("Subject");
582 # Fetch Subject of article 3345.
584 $c->xhdr("Subject", 3345);
585 # Fetch Subjects of articles 3345-9873
587 $c->xhdr("Subject", 3345, 9873);
588 # Fetch Message-ID of articles 3345-9873
590 $c->xhdr("", 3345,9873);
591 # Fetch Subject for article with Message-ID
593 $c->xhdr("Subject", '<797t0g$25f10@foo.com>');
594 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 Returns headers as an array of lines terminated by the
603 current EOL.
604 In scalar context a reference to the array is returned
606 instead of the array itself.
607 Examples:
609 # Fetch Subject header of article 1.
611 $c->xpat();
612 # Fetch "From" header of article 1.
614 $c->xpat("From");
615 # Fetch "From" of article 3345.
617 $c->xpat("From", 3345);
618 # Fetch "From" of articles 3345-9873 matching *foo*
620 $c->xpat("From", 3345, 9873, "*foo*");
621 # Fetch "Subject" of articles 3345-9873 matching
623 # *foo*, *bar*, *and*, *stuff*
624 $c->xpat("", 3345,9873, qw(*foo* *bar* *and* *stuff*));
625 xover Expects an article number or a starting and ending article
627 number representing a range of articles.
628 Returns overview information for each article as an array of
630 lines terminated by the current EOL.
631 In scalar context a reference to the array is returned
633 instead of the array itself.
634 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 #!/usr/local/bin/perl
640 require News::NNTPClient;
642 $c = new News::NNTPClient;
644 @fields = qw(numb subj from date mesg refr char line xref);
646 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 __END__
655 #
656 =item I<xthread>
657 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 Returns binary data as a scalar value.
663 Format of data returned is unknown at this time.
665 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 Returns index information for group as an array of lines
671 terminated by the current EOL.
672 In scalar context a reference to the array is returned
674 instead of the array itself.
675 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 Format of query is unknown at this time.
681
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.
689perl v5.28.0 2001-03-28 NNTPClient(3)