2.0. Newsreader Extensions
Newsreader extensions are those which are primarily used by
newsreading clients. Following are the descriptions of each
newsreader extension commands and the responses which will be
returned by those commands.
Each command is shown in upper case for clarity, although case is
ignored in the interpretation of commands by the NNTP server. Any
parameters are shown in lower case. A parameter shown in [square
brackets] is optional. For example, [GMT] indicates that the
triglyph GMT may present or omitted. A parameter that may be
repeated is followed by an ellipsis. Mutually exclusive parameters
are separated by a vertical bar (|) character. For example,
ggg| indicates that a group name or a may
be specified, but not both. Some parameters, notably ,
is case specific. See RFC 1036 for these details.
Also, certain commands make use of a pattern for selection of
multiple news groups. The pattern in all cases is based on the
wildmat [4] format introduced by Rich Salz in 1986. Arguments
expected to be in wildmat format will be represented by the string
wildmat. This format is discussed in detail in section 3.3 of this
document.
2.1.1. Extensions to the LIST command
The original LIST command took no arguments in RFC 977 and returned
the contents of the active file in a specific format. Since the
original newsreaders made use of other information available in the
news transport software in addition to the active file, extensions to
the LIST command were created to make that information available to
NNTP newsreaders. There may be other extensions to the LIST command
that simply return the contents of a file. This approach is
suggested over the addition of over verbs. For example, LIST MOTD
could be used instead of adding XMOTD.
2.1.2. LIST ACTIVE
LIST ACTIVE [wildmat]
LIST ACTIVE is exactly the same as the LIST command specified in RFC
977 . The responses and the format should exactly match the LIST
command without arguments. If the optional matching parameter is
specified, the list is limited to only the groups that match the
pattern. Specifying a single group is usually very efficient for the
server, and multiple groups may be specified by using wildmat
patterns (described later in this document), not regular expressions.
If nothing is matched an empty list is returned, not an error. This
command first appeared in the UNIX reference version.
2.1.3. LIST ACTIVE.TIMES
LIST ACTIVE.TIMES
The active.times file is maintained by some news transports systems
to contain information about the when and who created a particular
news group. The format of this file generally include three fields.
The first field is the name of the news group. The second is the
time when this group was created on this news server measured in
seconds since January 1, 1970. The third is the email address of the
entity that created the news group. When executed, the information
is displayed following the 215 response. When display is completed,
the server will send a period on a line by itself. If the
information is not available, the server will return the 503 error
response. This command first appeared in the UNIX reference version.
2.1.3.1. Responses
215 information follows
503 program error, function not performed
2.1.4. LIST DISTRIBUTIONS
LIST DISTRIBUTIONS
The distributions file is maintained by some news transport systems
to contain information about valid values for the Distribution: line
in a news article header and about what the values mean. Each line
contains two fields, the value and a short explanation on the meaning
of the value. When executed, the information is displayed following
the 215 response. When display is completed, the server will send a
period on a line by itself. If the information is not available, the
server will return the 503 error response. This command first
appeared in the UNIX reference version.
2.1.4.1. Responses
215 information follows
503 program error, function not performed
2.1.5. LIST DISTRIB.PATS
LIST DISTRIB.PATS
The distrib.pats file is maintained by some news transport systems to
contain default values for the Distribution: line in a news article
header when posting to particular news groups. This information
could be used to provide a default value for the Distribution: line
in the header when posting an article. The information returned
involves three fields separated by colons. The first column is a
weight. The second is a group name or a pattern that can be used to
match a group name in the wildmat format. The third is the value of
the Distribution: line that should be used when the group name
matches and the weight value is the highest. All this processing is
done by the news posting client and not by the server itself. The
server just provides this information to the client for it to use or
ignore as it chooses. When executed, the information is displayed
following the 215 response. When display is completed, the server
will send a period on a line by itself. If the information is not
available, the server will return the 503 error response. This
command first appeared in INN.
2.1.5.1. Responses
215 information follows
503 program error, function not performed
2.1.6. LIST NEWSGROUPS
LIST NEWSGROUPS [wildmat]
The newsgroups file is maintained by some news transport systems to
contain the name of each news group which is active on the server and
a short description about the purpose of each news group. Each line
in the file contains two fields, the news group name and a short
explanation of the purpose of that news group. When executed, the
information is displayed following the 215 response. When display is
completed, the server will send a period on a line by itself. If the
information is not available, the server will return the 503
response. If the optional matching parameter is specified, the list
is limited to only the groups that match the pattern (no matching is
done on the group descriptions). Specifying a single group is
usually very efficient for the server, and multiple groups may be
specified by using wildmat patterns (similar to file globbing), not
regular expressions. If nothing is matched an empty list is
returned, not an error.
When the optional parameter is specified, this command is equivalent
to the XGTITLE command, though the response code are different.
215 information follows
503 program error, function not performed
2.1.7. LIST OVERVIEW.FMT
LIST OVERVIEW.FMT
The overview.fmt file is maintained by some news transport systems to
contain the order in which header information is stored in the
overview databases for each news group. When executed, news article
header fields are displayed one line at a time in the order in which
they are stored in the overview database [5] following the 215
response. When display is completed, the server will send a period
on a line by itself. If the information is not available, the server
will return the 503 response.
Please note that if the header has the word "full" (without quotes)
after the colon, the header's name is prepended to its field in the
output returned by the server.
Many newsreaders work better if Xref: is one of the optional fields.
It is STRONGLY recommended that this command be implemented in any
server that implements the XOVER command. See section 2.8 for more
details about the XOVER command.
2.1.7.1. Responses
215 information follows
503 program error, function not performed
2.1.8. LIST SUBSCRIPTIONS
LIST SUBSCRIPTIONS
This command is used to get a default subscription list for new users
of this server. The order of groups is significant.
When this list is available, it is preceded by the 215 response and
followed by a period on a line by itself. When this list is not
available, the server returns a 503 response code.
2.1.8.1. Responses
215 information follows
503 program error, function not performed
2.2. LISTGROUP
LISTGROUP [ggg]
The LISTGROUP command is used to get a listing of all the article
numbers in a particular news group.
The optional parameter ggg is the name of the news group to be
selected (e.g. "news.software.b"). A list of valid news groups may
be obtained from the LIST command. If no group is specified, the
current group is used as the default argument.
The successful selection response will be a list of the article
numbers in the group followed by a period on a line by itself.
When a valid group is selected by means of this command, the
internally maintained "current article pointer" is set to the first
article in the group. If an invalid group is specified, the
previously selected group and article remain selected. If an empty
news group is selected, the "current article pointer" is in an
indeterminate state and should not be used.
Note that the name of the news group is not case-dependent. It must
otherwise match a news group obtained from the LIST command or an
error will result.
2.2.1. Responses
211 list of article numbers follow
412 Not currently in newsgroup
502 no permission
2.3. MODE READER
MODE READER is used by the client to indicate to the server that it
is a news reading client. Some implementations make use of this
information to reconfigure themselves for better performance in
responding to news reader commands. This command can be contrasted
with the SLAVE command in RFC 977, which was not widely implemented.
MODE READER was first available in INN.
2.3.1. Responses
200 Hello, you can post
201 Hello, you can't post
2.4. XGTITLE
XGTITLE [wildmat]
The XGTITLE command is used to retrieve news group descriptions for
specific news groups.
This extension first appeared in ANU-NEWS, an NNTP implementation for
DEC's VMS. The optional parameter is a pattern in wildmat format.
When executed, a 282 response is given followed by lines that have
two fields, the news group name (which matches the pattern in the
argument) and a short explanation of the purpose of the news group.
When no argument is specified, the default argument is the current
group name. When display is completed, the server sends a period on
a line by itself.
Please note that this command and the LIST NEWSGROUP command provide
the same functionality with different response codes.
Since this command provides the same functionality as LIST NEWSGROUP
it is suggested that this extension be deprecated and no longer be
used in newsreading clients.
Note that there is a conflict in one of the response codes from
XGTITLE and some of the authentication extensions.
2.5.1. Responses
481 Groups and descriptions unavailable
282 list of groups and descriptions follows
2.6. XHDR
XHDR header [range|]
The XHDR command is used to retrieve specific headers from specific
articles.
The required parameter is the name of a header line (e.g. "subject")
in a news group article. See RFC 1036 for a list of valid header
lines. The optional range argument may be any of the following:
an article number
an article number followed by a dash to indicate
all following
an article number followed by a dash followed by
another article number
The optional message-id argument indicates a specific article. The
range and message-id arguments are mutually exclusive. If no
argument is specified, then information from the current article is
displayed. Successful responses start with a 221 response followed
by a the matched headers from all matched messages. Each line
containing matched headers returned by the server has an article
number (or message ID, if a message ID was specified in the command),
then one or more spaces, then the value of the requested header in
that article. Once the output is complete, a period is sent on a
line by itself. If the optional argument is a message-id and no such
article exists, the 430 error response is returned. If a range is
specified, a news group must have been selected earlier, else a 412
error response is returned. If no articles are in the range
specified, a 420 error response is returned by the server. A 502
response will be returned if the client only has permission to
transfer articles.
Some implementations will return "(none)" followed by a period on a
line by itself if no headers match in any of the articles searched.
Others return the 221 response code followed by a period on a line by
itself.
The XHDR command has been available in the UNIX reference
implementation from its first release. However, until now, it has
been documented only in the source for the server.
2.6.1. Responses
221 Header follows
412 No news group current selected
420 No current article selected
430 no such article
502 no permission
2.7. XINDEX
XINDEX ggg
The XINDEX command is used to retrieve an index file in the format of
originally created for use by the TIN [6] news reader.
The required parameter ggg is the name of the news group to be
selected (e.g. "news.software.b"). A list of valid news groups may
be obtained from the LIST command.
The successful selection response will return index file in the
format used by the TIN news reader followed by a period on a line by
itself.
When a valid group is selected by means of this command, the
internally maintained "current article pointer" is set to the first
article in the group. If an invalid group is specified, the
previously selected group and article remain selected. If an empty
news group is selected, the "current article pointer" is in an
indeterminate state and should not be used.
Note that the name of the news group is not case-dependent. It must
otherwise match a news group obtained from the LIST command or an
error will result.
The format of the tin-style index file is discussed in the
documentation for the TIN newsreader. Since more recent versions of
TIN support the news overview (NOV) format, it is recommended that
this extension become historic and no longer be used in current
servers or future implementations.
2.7.1. Responses
218 tin-style index follows
418 no tin-style index is available for this news group
2.8. XOVER
XOVER [range]
The XOVER command returns information from the overview database for
the article(s) specified. This command was originally suggested as
part of the OVERVIEW work described in "The Design of a Common
Newsgroup Overview Database for Newsreaders" by Geoff Collyer. This
document is distributed in the Cnews distribution. The optional
range argument may be any of the following:
an article number
an article number followed by a dash to indicate
all following
an article number followed by a dash followed by
another article number
If no argument is specified, then information from the current
article is displayed. Successful responses start with a 224 response
followed by the overview information for all matched messages. Once
the output is complete, a period is sent on a line by itself. If no
argument is specified, the information for the current article is
returned. A news group must have been selected earlier, else a 412
error response is returned. If no articles are in the range
specified, a 420 error response is returned by the server. A 502
response will be returned if the client only has permission to
transfer articles.
Each line of output will be formatted with the article number,
followed by each of the headers in the overview database or the
article itself (when the data is not available in the overview
database) for that article separated by a tab character. The
sequence of fields must be in this order: subject, author, date,
message-id, references, byte count, and line count. Other optional
fields may follow line count. Other optional fields may follow line
count. These fields are specified by examining the response to the
LIST OVERVIEW.FMT command. Where no data exists, a null field must
be provided (i.e. the output will have two tab characters adjacent to
each other). Servers should not output fields for articles that have
been removed since the XOVER database was created.
The LIST OVERVIEW.FMT command should be implemented if XOVER is
implemented. A client can use LIST OVERVIEW.FMT to determine what
optional fields and in which order all fields will be supplied by
the XOVER command. See Section 2.1.7 for more details about the LIST
OVERVIEW.FMT command.
Note that any tab and end-of-line characters in any header data that
is returned will be converted to a space character.
2.8.1. Responses
224 Overview information follows
412 No news group current selected
420 No article(s) selected
502 no permission
2.9. XPAT
XPAT header range| pat [pat...]
The XPAT command is used to retrieve specific headers from specific
articles, based on pattern matching on the contents of the header.
This command was first available in INN.
The required header parameter is the name of a header line (e.g.
"subject") in a news group article. See RFC 1036 for a list of valid
header lines. The required range argument may be any of the
following:
an article number
an article number followed by a dash to indicate
all following
an article number followed by a dash followed by
another article number
The required message-id argument indicates a specific article. The
range and message-id arguments are mutually exclusive. At least one
pattern in wildmat must be specified as well. If there are
additional arguments the are joined together separated by a single
space to form one complete pattern. Successful responses start with
a 221 response followed by a the headers from all messages in which
the pattern matched the contents of the specified header line. This
includes an empty list. Once the output is complete, a period is
sent on a line by itself. If the optional argument is a message-id
and no such article exists, the 430 error response is returned. A
502 response will be returned if the client only has permission to
transfer articles.
2.9.1. Responses
221 Header follows
430 no such article
502 no permission
2.10. The XPATH command
XPATH
The XPATH command is used to determine the filenames in which an
article is filed. It first appeared in INN.
The required parameter message-id is the message id of an article as
are unique, but articles may be crossposted to multiple groups. The
response to an XPATH command will include a listing of all filenames
in which an article is stored separated by spaces or a response
indicating that no article with the specified message-id exists. The
returned data is only useful if the news client knows the
implementation details of the server. Because of this, it is
recommended that client avoid using this command.
2.10.1. Responses
223 path1[ path2 ...]
430 no such article on server
2.11. The XROVER command
XROVER [range]
The XROVER command returns reference information from the overview
database for the article(s) specified. This command first appeared
in the Unix reference implementation. The optional range argument
may be any of the following:
an article number
an article number followed by a dash to indicate
all following
an article number followed by a dash followed by
another article number
Successful responses start with a 224 response followed by the
contents of reference information for all matched messages. Once the
output is complete, a period is sent on a line by itself. If no
argument is specified, the information for the current article is
returned. A news group must have been selected earlier, else a 412
error response is returned. If no articles are in the range
specified, a 420 error response is returned by the server. A 502
response will be returned if the client only has permission to
transfer articles.
The output will be formatted with the article number, followed by the
contents of the References: line for that article, but does not
contain the field name itself.
This command provides the same basic functionality as using the XHDR
command and "references" as the header argument.
2.11.1. Responses
224 Overview information follows
412 No news group current selected
420 No article(s) selected
502 no permission
2.12. XTHREAD
XTHREAD [DBINIT|THREAD]
The XTHREAD command is used to retrieve threading information
in format of originally created for use by the TRN [6] news
reader.
The command XTHREAD DBINIT may be issued prior to entering
any groups to see if a thread database exists. If it does,
the database's byte order and version number are returned
as binary data.
If no parameter is given, XTHREAD THREAD is assumed.
To use XTHREAD THREAD, a news group must have been selected
earlier, else a 412 error response is returned.
A 502 response will be returned if the client only has
permission to transfer articles. A 503 response is returned
if the threading files are not available.
The format of the trn-style thread format is discussed in
the documentation for the TRN newsreader. Since more recent
versions of TRN support the news overview (NOV) format, it
is recommended that this extension become historic and no
longer be used in current servers or future implementations.
2.12.1. Responses
288 Binary data to follow
412 No newsgroup current selected
502 No permission
503 program error, function not performed
|