Project: Webinterface II - Msgbase Structures: Zvon - RFC 2980 [Common NNTP Extensions] - Newsreader Extensions

AMBROSIA60-Portal  Webinterface II Project
ZVON > RFC Repository > RFC 2980
Prev | Next |

3. 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|<message-id> indicates that  a group name or a <message-id> may
   be specified, but not both.  Some parameters, notably <message-id>,
   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.

3.1. Extensions to the LIST command

   The original LIST command took no arguments in RFC 977prop 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.

3.1.1. LIST ACTIVE

   LIST ACTIVE [wildmat]

   LIST ACTIVE is exactly the same as the LIST command specified in RFC
   977prop.  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.

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

3.1.2.1. Responses

      215 information follows
      503 program error, function not performed

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

3.1.3.1. Responses

      215 information follows
      503 program error, function not performed

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

3.1.4.1. Responses

      215 information follows
      503 program error, function not performed

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

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

3.1.6.1. Responses

      215 information follows
      503 program error, function not performed

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

3.1.7.1. Responses

      215 information follows
      503 program error, function not performed

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

3.2.1. Responses

      211 list of article numbers follow
      412 Not currently in newsgroup
      502 no permission

3.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 977prop, which was not widely implemented.
   MODE READER was first available in INN.

3.3.1. Responses

      200 Hello, you can post
      201 Hello, you can't post

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

3.4.1. Responses

      481 Groups and descriptions unavailable
      282 list of groups and descriptions follows

3.5. XHDR

   XHDR header [range|<message-id>]

   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.

3.5.1. Responses

      221 Header follows
      412 No news group current selected
      420 No current article selected
      430 no such article
      502 no permission

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

3.6.1. Responses

      218 tin-style index follows
      418 no tin-style index is available for this news group

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

3.7.1. Responses

      224 Overview information follows
      412 No news group current selected
      420 No article(s) selected
      502 no permission

3.8. XPAT

   XPAT header range|<message-id> 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.

3.8.1. Responses

      221 Header follows
      430 no such article
      502 no permission

3.9. The XPATH command

   XPATH <message-id>

   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
   shown in that article's message-id header.  According to RFC 1036
   [3], all message ids for all articles within the netnews environment
   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.

3.9.1. Responses

      223 path1[ path2 ...]
      430 no such article on server

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

3.10.1. Responses

      224 Overview information follows
      412 No news group current selected
      420 No article(s) selected
      502 no permission

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

3.11.1. Responses

      288 Binary data to follow
      412 No newsgroup current selected
      502 No permission
      503 program error, function not performed


ZVON > RFC Repository > RFC 2980
Prev | Next |


© 2003-2024 by Ulrich Schroeter   00470