Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
NNTPClient(3)	      User Contributed Perl Documentation	 NNTPClient(3)

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

SYNOPSIS
	   use News::NNTPClient;

	   $c =	new News::NNTPClient;
	   $c =	new News::NNTPClient($server);
	   $c =	new News::NNTPClient($server, $port);
	   $c =	new News::NNTPClient($server, $port, $debug);

DESCRIPTION
       This module implements a	client interface to NNTP, enabling a Perl 5
       application to talk to NNTP servers.  It	uses the OOP (Object Oriented
       Programming) interface introduced with Perl 5.

       NNTPClient exports nothing.

       A new NNTPClient	object must be created with the	new method.  Once this
       has been	done, all NNTP commands	are accessed through this object.

       Here are	a couple of short examples.  The first prints all articles in
       the "test" newsgroup:

	 #!/usr/local/bin/perl -w

	 use News::NNTPClient;

	 $c = new News::NNTPClient;

	 ($first, $last) = ($c->group("test"));

	 for (;	$first <= $last; $first++) {
	     print $c->article($first);
	 }

	 __END__

       This example prints the body of all articles in the "test" newsgroup
       newer than one hour:

	 #!/usr/local/bin/perl -w

	 require News::NNTPClient;

	 $c = new News::NNTPClient;

	 foreach ($c->newnews("test", time - 3600)) {
	     print $c->body($_);
	 }

	 __END__

   NNTPClient Commands
       These commands are used to manipulate the NNTPClient object, and	aren't
       directly	related	to commands available on any NNTP server.

       new	 Use this to create a new NNTP connection. It takes three
		 arguments, a hostname,	a port and a debug flag.  It calls
		 initialize.  Use an empty argument to specify defaults.

		 If port is omitted or blank (""), looks for environment
		 variable NNTPPORT, service "nntp", or uses 119.

		 If host is omitted or empty (""), looks for environment
		 variable NNTPSERVER or	uses "news".

		 Examples:

		   $c =	new News::NNTPClient;
		 or
		   $c =	new News::NNTPClient("newsserver.some.where");
		 or
		   $c =	new News::NNTPClient("experimental", 9999);
		 or
		   # Specify debug but use defaults.
		   $c =	new News::NNTPClient("", "", 2);

		 Returns a blessed reference, representing a new NNTP
		 connection.

       initialize
		 Calls port, host, connect, and	response, in that order.  If
		 any of	these fail, initialization is aborted.

       connect	 Connects to current host/port.	 Not normally needed, as the
		 new method does this for you.	Closes any existing
		 connection.  Sets the posting status.	See the	postok method.

       host	 Sets the host that will be used on the	next connect.  Not
		 normally needed, as the new method does this for you.

		 Without an argument, returns current host.

		 Argument can be hostname or dotted quad, for example,
		 "15.2.174.218".

		 Returns fully qualified host name.

       port	 Sets the port that will be used on the	next connect.  Not
		 normally needed, as the new method does this for you.

		 Without an argument, returns current port.

		 Argument can be port number or	name.  If it is	a name,	it
		 must be a valid service.

		 Returns port number.

       debug	 Sets the debug	level.

		 Without an argument, returns current debug level.

		 There are currently three debug levels.  Level	0, level 1,
		 and level 2.

		 At level 0 the	messages described for level 1 are not
		 produced.  Debug level	0 is a way of turning off messages
		 produced by the default debug level 1.	 Serious error
		 messages, such	as EOF (End Of File) on	the file handle, are
		 still produced.

		 At level 1, any NNTP command that results in a	result code of
		 400 or	greater	prints a warning message.  This	is the
		 default.

		 At level 2, in	addition to level 1 messages, status messages
		 are printed to	indicate actions taking	place.

		 Returns old debug value.

       ok	 Returns boolean status	of most	recent command.	 NNTP return
		 codes less than 400 are considered OK.	 Not often needed as
		 most commands return false upon failure anyway.

       okprint	 Returns boolean status	of most	recent command.	 NNTP return
		 codes less than 400 are considered OK.	 Prints	an error
		 message for return codes of 400 or greater unless debug level
		 is set	to zero	(0).

		 This method is	used internally	by most	commands, and could be
		 considered to be "for internal	use only".  You	should use the
		 return	status of commands directly to determine pass-fail, or
		 if needed the ok method can be	used to	check status later.

       message	 Returns the NNTP response message of the most recent command.

		 Example, as returned by NNTP server version 1.5.11t:

		   $c->slave;
		   print $c->message;

		   Kinky, kinky.  I don't support such perversions.

       code	 Returns the NNTP response code	of the most recent command.

		 Example:

		   $c->article(1);
		   print $c->code, "\n";

		   412

       postok	 Returns the post-ability status that was reported upon
		 connection or after the mode_reader command.

       eol	 Sets the End-Of-Line termination for text returned from the
		 server.

		 Returns the old EOL value.

		 Default is \n.

		 To set	EOL to nothing,	pass it	the empty string.

		 To query current EOL without setting it, call with no
		 arguments.

		 Example:

		   $old_eol = $c->eol();     # Get original.
		   $c->eol("");		     # Set EOL to nothing.
		   @article = $c->article(); # Fetch an	article.
		   $c->eol($old_eol);	     # Restore value.

       gmt	 Sets GMT mode.	 Returns old value.  To	query GMT mode without
		 setting it, call with no arguments.

		 A true	value means that GMT mode is used in the newgroups and
		 newnews functions.  A false value means that local time is
		 used.

       fourdigityear
		 Sets four digit year mode.  Returns old value.	 To query four
		 digit year mode without setting it, call with no arguments.

		 A true	value means that four digit years are used in the
		 newgroups and newnews functions.  A false value means that an
		 RFC977	compliant two digit year is used.

		 This function is available for	news servers that implemented
		 four digit years rather than deal with	non-y2k	compliment two
		 digit years.  RFC977 does not allow four digit	years, and
		 instead chooses the century closest.  I quote:

		     The closest century is assumed as part of the year	(i.e., 86
		     specifies 1986, 30	specifies 2030,	99 is 1999, 00 is 2000).

       version	 Returns version number.

		 This document represents @(#) $Revision: 0.37 $.

   NNTP	Commands
       These commands directly correlate to NNTP server	commands.  They	return
       a false value upon failure, true	upon success.  The truth value is
       usually some bit	of useful information.	For example, the stat command
       returns Message-ID if it	is successful.

       Some commands return multiple lines.  These lines are returned as an
       array in	array context, and as a	reference to an	array in scalar
       context.	 For example, if you do	this:

	 @lines	= $c->article(14);

       then @lines will	contain	the article, one line per array	element.
       However,	if you do this:

	 $lines	= $c->article(14);

       then $lines will	contain	a reference to an array.  This feature is for
       those that don't	like passing arrays from routine to routine.

       mode_reader
		 Some servers require this command to process NNTP client
		 commands.  Sets postok	status.	 See postok.

		 Returns OK status.

       article	 Retrieves an article from the server.	This is	the main
		 command for fetching articles.	 Expects a single argument, an
		 article number	or Message-ID.	If you use an article number,
		 you must be in	a news group.  See group.

		 Returns the header, a separating blank	line, and the body of
		 the article as	an array of lines terminated by	the current
		 EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 Examples:

		   print $c->article('<art1234@soom.oom>');

		   $c->group("test");

		   print $c->article(99);

       body	 Expects a single argument, an article number or Message-ID.

		 Returns the body of an	article	as an array of lines
		 terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 See article.

       head	 Expects a single argument, an article number or Message-ID.

		 Returns the head of the article as an array of	lines
		 terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 See article.

       stat	 Expects a single argument, an article number or Message-ID.

		 The STAT command is like the ARTICLE command except that it
		 does not return any text.  It can be used to set the "current
		 article pointer" if passed an article number, or to validate
		 a Message-ID if passed	a Message-ID.

		 Returns Message-ID if successful, otherwise returns false.

       last	 The "current article pointer" maintained by the server	is
		 moved to the previous article in the current news group.

		 Returns Message-ID if successful, otherwise returns false.

       next	 The "current article pointer" maintained by the server	is
		 moved to the next article in the current news group.

		 Returns Message-ID if successful, otherwise returns false.

       group	 Expects a single argument, the	name of	a valid	news group.

		 This command sets the current news group as maintained	by the
		 server.  It also sets the server maintained "current article
		 pointer" to the first article in the group.  This enables the
		 use of	certain	other server commands, such as article,	head,
		 body, stat, last, and next.  Also sets	the current group in
		 the NNTPClient	object,	which is used by the newnews and
		 xindex	commands.

		 Returns (first, last) in list context,	or "first-last"	in
		 scalar	context, where first and last are the first and	last
		 article numbers as reported by	the group command.  Returns
		 false if there	is an error.

		 It is an error	to attempt to select a non-existent news
		 group.

		 If the	estimated article count	is needed, it can be extracted
		 from the message.  See	message.

       list	 Accepts two optional arguments.  The first can	be used
		 indicate the type of list desired.  List type depends on
		 server.  The second is	a pattern that is use by some list
		 types.

		 Examples:

		   print $c->list();
		   print $c->list('active');
		   print $c->list('active', 'local.*');
		   print $c->list('newsgroups');

		 With an argument of "active" or with no arguments, this
		 command returns a list	of valid newsgroups and	associated
		 information.  The format is:

		   group last first p

		 where group is	the news group name, last is the article
		 number	of the last article, first is the article number of
		 the first article, and	p is flag indicating if	posting	is
		 allowed.  A 'y' flag is an indication that posting is
		 allowed.

		 Other possible	arguments are: newsgroups, distributions,
		 subscriptions for B-News, and active.times, distributions,
		 distrib.pats, newsgroups, overview.fmt	for INN.

		 Returns an array of lines terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       newgroups Expects at least one argument representing the	date/time in
		 seconds, or in	"YYYYMMDDA HHMMSSA [GMT]" format.  The GMT
		 part is optional.  If you wish	to use GMT with	the seconds
		 format, first call gmt.  Remaining arguments are used as
		 distributions.

		 Example, print	all new	groups in the "comp" and/or "news"
		 hierarchy as of one hour ago:

		   print $c->newgroups(time() -	3600, "comp", "news");

		 Returns list of new news group	names as an array of lines
		 terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       newnews	 Expects one, two, or more arguments.

		 If the	first argument is a group name,	it looks for new news
		 in that group,	and the	date/time is the second	argument.  If
		 the first argument represents the date/time in	seconds	or in
		 "YYYYMMDD HHMMSS [GMT]" format, then the group	is is last
		 group set via the group command. If no	group command has been
		 issued	then the group is "*", representing all	groups.	 If
		 you wish to use GMT in	seconds	format for the time, first
		 call gmt.  Remaining arguments	are use	to restrict search to
		 certain distribution(s).

		 Returns a list	of Message-IDs of articles that	have been
		 posted	or received since the specified	time.

		 Examples:

		   # Hour old news in news group "test".
		   $c->newnews("test", time() -	3600);
		 or
		   # Hour old in all groups.
		   $c->newnews(time() -	3600);
		 or
		   $c->newnews("*", time() - 3600);
		 or
		   # Hour old news in news group "test".
		   $c->group("test");
		   $c->newnews(time() -	3600);

		 The group argument can	include	an asterisk "*"	to specify a
		 range news groups.  It	can also include multiple news groups,
		 separated by a	comma ",".

		 Example:

		   $c->newnews("comp.*.sources,alt.sources", time() - 3600);

		 An exclamation	point "!" may be used to negate	the selection
		 of certain groups.

		 Example:

		   $c->newnews("*sources*,!*.d,!*.wanted", time() - 3600);

		 Any additional	distribution arguments will be concatenated
		 together and send as a	distribution list.  The	distribution
		 list will limit articles to those that	have a Distribution:
		 header	containing one of the distributions passed.

		 Example:

		   $c->newnews("*", time() - 3600, "local", "na");

		 Returns Message-IDs of	new articles as	an array of lines
		 terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       help	 Returns any server help information.  The format of the
		 information is	highly dependent on the	server,	but usually
		 contains a list of NNTP commands recognized by	the server.

		 Returns an array of lines terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       post	 Post an article.  Expects data	to be posted as	an array of
		 lines.	 Most servers expect, at a minimum, Newsgroups and
		 Subject headers.  Be sure to separate the header from the
		 body with a neck, er blank line.

		 Example:

		   @header = ("Newsgroups: test", "Subject: test", "From: tester");
		   @body   = ("This is the body	of the article");

		   $c->post(@header, "", @body);

		 There aren't really three arguments.  Perl folds all
		 arguments into	a single list.	You could also do this:

		   @article = ("Newsgroups: test", "Subject: test", "From: tester", "",	"Body");
		   $c->post(@article);

		 or even this:

		   $c->post("Newsgroups: test",	"Subject: test", "From:	tester", "", "Body");

		 Any "\n" characters at	the end	of a line will be trimmed.

		 Returns status.

       ihave	 Transfer an article.  Expects an article Message-ID and the
		 article to be sent as an array	of lines.

		 Example:

		   # Fetch article from	server on $c
		   @article = $c->article($artid);

		   # Send to server on $d
		   if ($d->ihave($artid, @article)) {
		       print "Article transfered\n";
		   } else {
		       print "Article rejected:	", $d->message,	"\n";
		   }

       slave	 Doesn't do anything on	most servers.  Included	for
		 completeness.

       DESTROY	 This method is	called whenever	the the	object created by
		 News::NNTPClient::new is destroyed.  It calls quit to close
		 the connection.

       quit	 Send the NNTP quit command and	close the connection.  The
		 connection can	be then	be re-opened with the connect method.
		 Quit will automatically be called when	the object is
		 destroyed, so there is	no need	to explicitly call quit	before
		 exiting your program.

   Extended NNTP Commands
       These commands also directly correlate NNTP server commands, but	are
       not mentioned in	RFC977,	and are	not part of the	standard.  However,
       many servers implement them, so they are	included as part of this
       package for your	convenience.  If a command is not recognized by	a
       server, the server usually returns code 500, command unrecognized.

       authinfo	 Expects two arguments,	user and password.

       date	 Returns server	date in	"YYYYMMDDhhmmss" format.

       listgroup Expects one argument, a group name.  Default is current
		 group.

		 Returns article numbers as an array of	lines terminated by
		 the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       xmotd	 Expects one argument of unix time in seconds or as a string
		 in the	form "YYYYMMDD HHMMSS".

		 Returns the news servers "Message Of The Day" as an array of
		 lines terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 For example, the following will always	print the message of
		 the day, if there is any:

		   print $c->xmotd(1);
		   NNTP	Server News2

		   News	administrator is Joseph	Blough <joeblo@news.foo.com>

       xgtitle	 Expects one argument of a group pattern.  Default is current
		 group.

		 Returns group titles an array of lines	terminated by the
		 current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 Example:

		   print $c->xgtitle("bit.listserv.v*");

		   bit.listserv.valert-l   Virus Alert List. (Moderated)
		   bit.listserv.vfort-l	   VS-Fortran Discussion List.
		   bit.listserv.vm-util	   VM Utilities	Discussion List.
		   bit.listserv.vmesa-l	   VM/ESA Mailing List.
		   bit.listserv.vmslsv-l   VAX/VMS LISTSERV Discussion List.
		   bit.listserv.vmxa-l	   VM/XA Discussion List.
		   bit.listserv.vnews-l	   VNEWS Discussion List.
		   bit.listserv.vpiej-l	   Electronic Publishing Discussion

       xpath	 Expects one argument of an article Message-ID.	 Returns the
		 path name of the file on the server.

		 Example:

		   print print $c->xpath(q(<43bq5l$7b5@news.dtc.hp.com>))'
		   hp/test/4469

       xhdr	 Fetch header for a range of articles.	First argument is name
		 of header to fetch.  If omitted or blank, default to Message-
		 ID.  Second argument is start of article range.  If omitted,
		 defaults to 1.	 Third argument	is end of range.  If omitted,
		 defaults to "".  The second argument can also be a Message-
		 ID.

		 Returns headers as an array of	lines terminated by the
		 current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 Examples:

		   # Fetch Message-ID of article 1.
		   $c->xhdr();

		   # Fetch Subject of article 1.
		   $c->xhdr("Subject");

		   # Fetch Subject of article 3345.
		   $c->xhdr("Subject", 3345);

		   # Fetch Subjects of articles	3345-9873
		   $c->xhdr("Subject", 3345, 9873);

		   # Fetch Message-ID of articles 3345-9873
		   $c->xhdr("",	3345,9873);

		   # Fetch Subject for article with Message-ID
		   $c->xhdr("Subject", '<797t0g$25f10@foo.com>');

       xpat	 Fetch header for a range of articles matching one or more
		 patterns.  First argument is name of header to	fetch.	If
		 omitted or blank, default to Subject.	Second argument	is
		 start of article range.  If omitted, defaults to 1.  Next
		 argument is end of range.  Remaining arguments	are patterns
		 to match.  Some servers use "*" for wildcard.

		 Returns headers as an array of	lines terminated by the
		 current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 Examples:

		   # Fetch Subject header of article 1.
		   $c->xpat();

		   # Fetch "From" header of article 1.
		   $c->xpat("From");

		   # Fetch "From" of article 3345.
		   $c->xpat("From", 3345);

		   # Fetch "From" of articles 3345-9873	matching *foo*
		   $c->xpat("From", 3345, 9873,	"*foo*");

		   # Fetch "Subject" of	articles 3345-9873 matching
		   # *foo*, *bar*, *and*, *stuff*
		   $c->xpat("",	3345,9873, qw(*foo* *bar* *and*	*stuff*));

       xover	 Expects an article number or a	starting and ending article
		 number	representing a range of	articles.

		 Returns overview information for each article as an array of
		 lines terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

		 Xover generally returns items separated by tabs.  Here	is an
		 example that prints out the xover fields from all messages in
		 the "test" news group.

		   #!/usr/local/bin/perl

		   require News::NNTPClient;

		   $c =	new News::NNTPClient;

		   @fields = qw(numb subj from date mesg refr char line	xref);

		   foreach $xover ($c->xover($c->group("test"))) {
		       %fields = ();
		       @fields{@fields}	= split	/\t/, $xover;
		       print map { "$_:	$fields{$_}\n" } @fields;
		       print "\n";
		   }

		   __END__
						 #
		 =item I<xthread>

		 Expects zero or one argument.	Value of argument doesn't
		 matter.  If present, dbinit command is	sent.  If absent,
		 thread	command	is sent.

		 Returns binary	data as	a scalar value.

		 Format	of data	returned is unknown at this time.

       xindex	 Expects one argument, a group name.  If omitted, defaults to
		 the group set by last group command.  If there	hasn't been a
		 group command,	it returns an error;

		 Returns index information for group as	an array of lines
		 terminated by the current EOL.

		 In scalar context a reference to the array is returned
		 instead of the	array itself.

       xsearch	 Expects a query as an array of	lines which are	sent to	the
		 server, much like post.  Returns the result of	the search as
		 an array of lines or a	reference to same.

		 Format	of query is unknown at this time.

AUTHOR
       Rodger Anderson	<rodger@boi.hp.com>

COPYRIGHT
       Copyright 1995 Rodger Anderson. All rights reserved.  This module is
       free software; you can redistribute it and/or modify it under the same
       terms as	Perl itself.

perl v5.32.0			  2001-03-28			 NNTPClient(3)

NAME | SYNOPSIS | DESCRIPTION | AUTHOR | COPYRIGHT

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=News::NNTPClient&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help