The package nntp 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 command opens a socket connection to the specified NNTP server and
creates a new nntp object with an associated global Tcl command whose
name is nntpName. This command may be used to access the various
NNTP protocol commands for the new connection. The default port
number is "119" and the default host is "news". These defaults
can be overridden with the environment variables NNTPPORT and
NNTPHOST respectively.

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 article.

Query and configure options of the nntp connection object. Currently
only one option is supported, -binary. When set articles are
retrieved as binary data instead of text. The only methods affected by
this are article and body.

One application of this option would be the download of articles
containing yEnc encoded images. Although encoded the data is still
mostly binary and retrieving it as text will corrupt the information.

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.

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 element
in the list is one line of the headers of the article.

Returns a tcl list of valid newsgroups and associated 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 new newsgroups 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').

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 argument
since can be any time string that is understood by clock scan.

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.

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 message-id is valid but of questionable value, since a
selection by message-id does NOT alter the "current article pointer"

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.

msgid1-msgid2

All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.

msgid1msgid2

All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.

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
pattern(s) given in the pattern_list. field is the title of a
field in the header such as from, subject, 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.

msgid1msgid2

All messages between msgid1 and msgid2
(including msgid1 and msgid2) are queried.

This document, and the package it describes, will undoubtedly contain
bugs and other problems.
Please report such in the category nntp of the
Tcllib Trackers.
Please also report any ideas for enhancements you may have for either
package and/or documentation.