NAME
nntp - Tcl client for the NNTP protocol
SYNOPSIS
package require nntp ?0.1?
::nntp::nntp ?host? ?port? ?nntpName?
_________________________________________________________________
DESCRIPTION
The nntp package provides a simple Tcl-only client library
for the NNTP protocol. It works by opening the standard
NNTP socket on the server, and then providing a Tcl API to
access the NNTP protocol commands. All server errors are
returned as Tcl errors (thrown) which must be caught with
the Tcl catch command. The ::nntp::nntp command creates a
new nntp object with an associated Tcl command whose name
is returned by the ::nntp::nntp command (nntpName). This
command may be used to access the various NNTP protocol
commands. Some of the commands supported by this package
are not part of the nntp rfc (rfc 977) and will not be
available (or implemented) on all nntp servers. The com
mands have the following general form:
nntpName option ?arg arg ...?
Option and the args determine the exact behavior of the
command.
COMMANDS
::nntp::nntp ?host? ?port? ?nntpName?
Open a socket connection to a NNTP server. The
command returns the name of the global command that
can be used to access the nntp connection subse
quently. The default port number is 119 and the
default server is news which can be overridden with
the environment variables NNTPPORT and NNTPHOST
respectively.
nntpName article ?msgid?
Query the server for article msgid from the current
group. The article is returned as a valid tcl list
which contains the headers, followed by a blank
line, and then followed by the body of the article.
Each element in the list is one line of the arti
cle.
nntpName authinfo ?user? ?pass?
Send authentication information (username and pass
word) to the server.
Query the server for the body of the article msgid
from the current group. The body of the article is
returned as a valid tcl list. Each element in the
list is one line of the body of the article.
nntpName date
Query the server for the servers current date. The
date is returned in the format YYYYMMDDHHMMSS
nntpName group ?group?
Optionally set the current group, and retrieve
information about the currently selected group.
Returns the estimated number of articles in the
group followed by the number of the first article
in the group, followed by the last article in the
group, followed by the name of the group.
nntpName head ?msgid?
Query the server for the headers of the article
msgid from the current group. The headers of the
article are returned as a valid tcl list. Each ele
ment in the list is one line of the headers of the
article.
nntpName help
Retrieves a list of the commands that are supported
by the news server that is currently attached to.
nntpName last
Sets the current article pointer to point to the
previous message (if there is one) and returns the
msgid of that message.
nntpName list
Returns a tcl list of valid newsgroups and associ
ated information. Each newsgroup is returned as an
element in the tcl list with the following format:
group last first p
where <group> is the name of the newsgroup, <last>
is the number of the last known article currently
in that newsgroup, <first> is the number of the
first article currently in the newsgroup, and <p>
is either 'y' or 'n' indicating whether posting to
this newsgroup is allowed ('y') or prohibited
('n').
The <first> and <last> fields will always be
numeric. They may have leading zeros. If the
<last> field evaluates to less than the <first>
field, there are no articles currently on file in
the newsgroup.
Query the server for a list of all the messages
(message numbers) in the group specified by the
argument group or by the current group if the group
argument was not passed.
nntpName mode_reader
Query the server for its nntp 'MODE READER'
response string.
nntpName newgroups since
Query the server for a list of all the new news
groups created since the time specified by the
argument since. The argument since can be any time
string that is understood by clock scan. The tcl
list of newsgroups is returned in a similar form to
the list of groups returned by the nntpName list
command. Each element of the list has the form:
group last first p
where <group> is the name of the newsgroup, <last>
is the number of the last known article currently
in that newsgroup, <first> is the number of the
first article currently in the newsgroup, and <p>
is either 'y' or 'n' indicating whether posting to
this newsgroup is allowed ('y') or prohibited
('n').
nntpName newnews
Query the server for a list of new articles posted
to the current group in the last day.
nntpName newnews since
Query the server for a list of new articles posted
to the current group since the time specified by
the argument since. The argument since can be any
time string that is understood by clock scan.
nntpName newnews group ?since?
Query the server for a list of new articles posted
to the group specified by the argument group since
the time specified by the argument since (or in the
past day if no since argument is passed. The argu
ment since can be any time string that is under
stood by clock scan.
nntpName next
Sets the current article pointer to point to the
next message (if there is one) and returns the
msgid of that message.
nntpName post article
Posts an article of the form specified in RFC 850
nntpName slave
Identifies a connection as being made from a slave
nntp server. This might be used to indicate that
the connection is serving multiple people and
should be given priority. Actual use is entirely
implementation dependent and may vary from server
to server.
nntpName stat ?msgid?
The stat command is similar to the article command
except that no text is returned. When selecting by
message number within a group, the stat command
serves to set the current article pointer without
sending text. The returned acknowledgment response
will contain the message-id, which may be of some
value. Using the stat command to select by mes
sage-id is valid but of questionable value, since a
selection by message-id does NOT alter the "current
article pointer"
nntpName quit
Gracefully close the connection after sending a
NNTP QUIT command down the socket.
nntpName xgtitle ?group_pattern?
Returns a tcl list where each element is of the
form:
newsgroup description
If a group_pattern is specified then only news
groups that match the pattern will have their name
and description returned.
nntpName xhdr field ?range?
Returns the specified header field value for the
current message or for a list of messages from the
current group. field is the title of a field in
the header such as from, subject, date, etc. If
range is not specified or is "" then the current
message is queried. The command returns a list of
elements where each element has the form of:
msgid value
Where msgid is the number of the message and value
is the value set for the queried field. The range
argument can be in any of the following forms:
"" The current message is queried.
All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.
msgid1 msgid2
All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.
nntpName xover ?range?
Returns header information for the current message
or for a range of messages from the current group.
The information is returned in a tcl list where
each element is of the form:
msgid subject from date idstring bodysize header
size xref
If range is not specified or is "" then the current
message is queried. The range argument can be in
any of the following forms:
"" The current message is queried.
msgid1-msgid2
All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.
msgid1 msgid2
All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.
nntpName xpat field range ?pattern_list?
Returns the specified header field value for a
specified message or for a list of messages from
the current group where the messages match the pat
tern(s) given in the pattern_list. field is the
title of a field in the header such as from, sub
ject, date, etc. The information is returned in a
tcl list where each element is of the form:
msgid value
Where msgid is the number of the message and value
is the value set for the queried field. The range
argument can be in any of the following forms:
msgid The message specified by msgid is queried.
msgid1-msgid2
All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.
msgid1 msgid2
All messages between msgid1 and msgid2
KEYWORDS
news, nntp, nntpclient
Man(1) output converted with
man2html