7.  Information Commands

   This section lists other commands that may be used at any time
   between the beginning of a session and its termination.  Using these
   commands does not alter any state information, but the response
   generated from their use may provide useful information to clients.

7.1.  DATE

7.1.1.  Usage

   Indicating capability: READER

   Syntax
     DATE

   Responses
     111 yyyymmddhhmmss    Server date and time

   Parameters
     yyyymmddhhmmss    Current UTC date and time on server

7.1.2.  Description

   This command exists to help clients find out the current Coordinated
   Universal Time [TF.686-1] from the server's perspective.  This
   command SHOULD NOT be used as a substitute for NTP [RFC1305] but to
   provide information that might be useful when using the NEWNEWS
   command (see Section 7.4).

   The DATE command MUST return a timestamp from the same clock as is
   used for determining article arrival and group creation times (see
   Section 6).  This clock SHOULD be monotonic, and adjustments SHOULD
   be made by running it fast or slow compared to "real" time rather
   than by making sudden jumps.  A system providing NNTP service SHOULD
   keep the system clock as accurate as possible, either with NTP or by
   some other method.

   The server MUST return a 111 response specifying the date and time on
   the server in the form yyyymmddhhmmss.  This date and time is in
   Coordinated Universal Time.

7.1.3.  Examples

      [C] DATE
      [S] 111 19990623135624

7.2.  HELP

7.2.1.  Usage

   This command is mandatory.

   Syntax
     HELP

   Responses
     100    Help text follows (multi-line)

7.2.2.  Description

   This command provides a short summary of the commands that are
   understood by this implementation of the server.  The help text will
   be presented as a multi-line data block following the 100 response
   code.

   This text is not guaranteed to be in any particular format (but must
   be UTF-8) and MUST NOT be used by clients as a replacement for the
   CAPABILITIES command described in Section 5.2.

7.2.3.  Examples

      [C] HELP
      [S] 100 Help text follows
      [S] This is some help text.  There is no specific
      [S] formatting requirement for this test, though
      [S] it is customary for it to list the valid commands
      [S] and give a brief definition of what they do.
      [S] .

7.3.  NEWGROUPS

7.3.1.  Usage

   Indicating capability: READER

   Syntax
     NEWGROUPS date time [GMT]

   Responses
     231    List of new newsgroups follows (multi-line)

   Parameters
     date    Date in yymmdd or yyyymmdd format
     time    Time in hhmmss format

7.3.2.  Description

   This command returns a list of newsgroups created on the server since
   the specified date and time.  The results are in the same format as
   the LIST ACTIVE command (see Section 7.6.3).  However, they MAY
   include groups not available on the server (and so not returned by
   LIST ACTIVE) and MAY omit groups for which the creation date is not
   available.

   The date is specified as 6 or 8 digits in the format [xx]yymmdd,
   where xx is the first two digits of the year (19-99), yy is the last
   two digits of the year (00-99), mm is the month (01-12), and dd is
   the day of the month (01-31).  Clients SHOULD specify all four digits
   of the year.  If the first two digits of the year are not specified
   (this is supported only for backward compatibility), the year is to
   be taken from the current century if yy is smaller than or equal to
   the current year, and the previous century otherwise.

   The time is specified as 6 digits in the format hhmmss, where hh is
   the hours in the 24-hour clock (00-23), mm is the minutes (00-59),
   and ss is the seconds (00-60, to allow for leap seconds).  The token
   "GMT" specifies that the date and time are given in Coordinated
   Universal Time [TF.686-1]; if it is omitted, then the date and time
   are specified in the server's local timezone.  Note that there is no
   way of using the protocol specified in this document to establish the
   server's local timezone.

   Note that an empty list is a possible valid response and indicates
   that there are no new newsgroups since that date-time.

   Clients SHOULD make all queries using Coordinated Universal Time
   (i.e., by including the "GMT" argument) when possible.

7.3.3.  Examples

   Example where there are new groups:

      [C] NEWGROUPS 19990624 000000 GMT
      [S] 231 list of new newsgroups follows
      [S] alt.rfc-writers.recovery 4 1 y
      [S] tx.natives.recovery 89 56 y
      [S] .

   Example where there are no new groups:

      [C] NEWGROUPS 19990624 000000 GMT
      [S] 231 list of new newsgroups follows
      [S] .

7.4.  NEWNEWS

7.4.1.  Usage

   Indicating capability: NEWNEWS

   Syntax
     NEWNEWS wildmat date time [GMT]

   Responses
     230    List of new articles follows (multi-line)

   Parameters
     wildmat    Newsgroups of interest
     date       Date in yymmdd or yyyymmdd format
     time       Time in hhmmss format

7.4.2.  Description

   This command returns a list of message-ids of articles posted or
   received on the server, in the newsgroups whose names match the
   wildmat, since the specified date and time.  One message-id is sent
   on each line; the order of the response has no specific significance
   and may vary from response to response in the same session.  A
   message-id MAY appear more than once; if it does, it has the same
   meaning as if it appeared only once.

   Date and time are in the same format as the NEWGROUPS command (see
   Section 7.3).

   Note that an empty list is a possible valid response and indicates
   that there is currently no new news in the relevant groups.

   Clients SHOULD make all queries in Coordinated Universal Time (i.e.,
   by using the "GMT" argument) when possible.

7.4.3.  Examples

   Example where there are new articles:

      [C] NEWNEWS news.*,sci.* 19990624 000000 GMT
      [S] 230 list of new articles by message-id follows
      [S] <i.am.a.new.article@example.com>
      [S] <i.am.another.new.article@example.com>
      [S] .

   Example where there are no new articles:

      [C] NEWNEWS alt.* 19990624 000000 GMT
      [S] 230 list of new articles by message-id follows
      [S] .

7.5.  Time

   As described in Section 6, each article has an arrival timestamp.
   Each newsgroup also has a creation timestamp.  These timestamps are
   used by the NEWNEWS and NEWGROUP commands to construct their
   responses.

   Clients can ensure that they do not have gaps in lists of articles or
   groups by using the DATE command in the following manner:

   First session:
      Issue DATE command and record result.
      Issue NEWNEWS command using a previously chosen timestamp.

   Subsequent sessions:
      Issue DATE command and hold result in temporary storage.
      Issue NEWNEWS command using timestamp saved from previous session.
      Overwrite saved timestamp with that currently in temporary
      storage.

   In order to allow for minor errors, clients MAY want to adjust the
   timestamp back by two or three minutes before using it in NEWNEWS.

7.5.1.  Examples

   First session:

      [C] DATE
      [S] 111 20010203112233
      [C] NEWNEWS local.chat 20001231 235959 GMT
      [S] 230 list follows
      [S] <article.1@local.service>
      [S] <article.2@local.service>
      [S] <article.3@local.service>
      [S] .

   Second session (the client has subtracted 3 minutes from the
   timestamp returned previously):

      [C] DATE
      [S] 111 20010204003344
      [C] NEWNEWS local.chat 20010203 111933 GMT
      [S] 230 list follows
      [S] <article.3@local.service>
      [S] <article.4@local.service>
      [S] <article.5@local.service>
      [S] .

   Note how <article.3@local.service> arrived in the 3 minute gap and so
   is listed in both responses.

7.6.  The LIST Commands

   The LIST family of commands all return information that is multi-line
   and that can, in general, be expected not to change during the
   session.  Often the information is related to newsgroups, in which
   case the response has one line per newsgroup and a wildmat MAY be
   provided to restrict the groups for which information is returned.

   The set of available keywords (including those provided by
   extensions) is given in the capability list with capability label
   LIST.

7.6.1.  LIST

7.6.1.1.  Usage

   Indicating capability: LIST

   Syntax
     LIST [keyword [wildmat|argument]]

   Responses
     215    Information follows (multi-line)

   Parameters
     keyword     Information requested [1]
     argument    Specific to keyword
     wildmat     Groups of interest

   [1] If no keyword is provided, it defaults to ACTIVE.

7.6.1.2.  Description

   The LIST command allows the server to provide blocks of information
   to the client.  This information may be global or may be related to
   newsgroups; in the latter case, the information may be returned
   either for all groups or only for those matching a wildmat.  Each
   block of information is represented by a different keyword.  The
   command returns the specific information identified by the keyword.

   If the information is available, it is returned as a multi-line data
   block following the 215 response code.  The format of the information
   depends on the keyword.  The information MAY be affected by the
   additional argument, but the format MUST NOT be.

   If the information is based on newsgroups and the optional wildmat
   argument is specified, the response is limited to only the groups (if
   any) whose names match the wildmat and for which the information is
   available.

   Note that an empty list is a possible valid response; for a
   newsgroup-based keyword, it indicates that there are no groups
   meeting the above criteria.

   If the keyword is not recognised, or if an argument is specified and
   the keyword does not expect one, a 501 response code MUST BE
   returned.  If the keyword is recognised but the server does not
   maintain the information, a 503 response code MUST BE returned.

   The LIST command MUST NOT change the visible state of the server in
   any way; that is, the behaviour of subsequent commands MUST NOT be
   affected by whether the LIST command was issued.  For example, it
   MUST NOT make groups available that otherwise would not have been.

7.6.1.3.  Examples

   Example of LIST with the ACTIVE keyword:

      [C] LIST ACTIVE
      [S] 215 list of newsgroups follows
      [S] misc.test 3002322 3000234 y
      [S] comp.risks 442001 441099 m
      [S] alt.rfc-writers.recovery 4 1 y
      [S] tx.natives.recovery 89 56 y
      [S] tx.natives.recovery.d 11 9 n
      [S] .

   Example of LIST with no keyword:

      [C] LIST
      [S] 215 list of newsgroups follows
      [S] misc.test 3002322 3000234 y
      [S] comp.risks 442001 441099 m
      [S] alt.rfc-writers.recovery 4 1 y
      [S] tx.natives.recovery 89 56 y
      [S] tx.natives.recovery.d 11 9 n
      [S] .

   The output is identical to that of the previous example.

   Example of LIST on a newsgroup-based keyword with and without
   wildmat:

      [C] LIST ACTIVE.TIMES
      [S] 215 information follows
      [S] misc.test 930445408 <creatme@isc.org>
      [S] alt.rfc-writers.recovery 930562309 <m@example.com>
      [S] tx.natives.recovery 930678923 <sob@academ.com>
      [S] .
      [C] LIST ACTIVE.TIMES tx.*
      [S] 215 information follows
      [S] tx.natives.recovery 930678923 <sob@academ.com>
      [S] .

   Example of LIST returning an error where the keyword is recognized
   but the software does not maintain this information:

      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
      [S] .
      [C] LIST XTRA.DATA
      [S] 503 Data item not stored

   Example of LIST where the keyword is not recognised:

      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] LIST ACTIVE NEWSGROUPS ACTIVE.TIMES XTRA.DATA
      [S] .
      [C] LIST DISTRIB.PATS
      [S] 501 Syntax Error

7.6.2.  Standard LIST Keywords

   This specification defines the following LIST keywords:

   +--------------+---------------+------------------------------------+
   | Keyword      | Definition    | Status                             |
   +--------------+---------------+------------------------------------+
   | ACTIVE       | Section 7.6.3 | Mandatory if the READER capability |
   |              |               | is advertised                      |
   |              |               |                                    |
   | ACTIVE.TIMES | Section 7.6.4 | Optional                           |
   |              |               |                                    |
   | DISTRIB.PATS | Section 7.6.5 | Optional                           |
   |              |               |                                    |
   | HEADERS      | Section 8.6   | Mandatory if the HDR capability is |
   |              |               | advertised                         |
   |              |               |                                    |
   | NEWSGROUPS   | Section 7.6.6 | Mandatory if the READER capability |
   |              |               | is advertised                      |
   |              |               |                                    |
   | OVERVIEW.FMT | Section 8.4   | Mandatory if the OVER capability   |
   |              |               | is advertised                      |
   +--------------+---------------+------------------------------------+

   Where one of these LIST keywords is supported by a server, it MUST
   have the meaning given in the relevant sub-section.

7.6.3.  LIST ACTIVE

   This keyword MUST be supported by servers advertising the READER
   capability.

   LIST ACTIVE returns a list of valid newsgroups and associated
   information.  If no wildmat is specified, the server MUST include
   every group that the client is permitted to select with the GROUP
   command (Section 6.1.1).  Each line of this list consists of four
   fields separated from each other by one or more spaces:

   o  The name of the newsgroup.
   o  The reported high water mark for the group.
   o  The reported low water mark for the group.
   o  The current status of the group on this server.

   The reported high and low water marks are as described in the GROUP
   command (see Section 6.1.1), but note that they are in the opposite
   order to the 211 response to that command.

   The status field is typically one of the following:

   "y" Posting is permitted.

   "n" Posting is not permitted.

   "m" Postings will be forwarded to the newsgroup moderator.

   The server SHOULD use these values when these meanings are required
   and MUST NOT use them with any other meaning.  Other values for the
   status may exist; the definition of these other values and the
   circumstances under which they are returned may be specified in an
   extension or may be private to the server.  A client SHOULD treat an
   unrecognized status as giving no information.

   The status of a newsgroup only indicates how posts to that newsgroup
   are normally processed and is not necessarily customised to the
   specific client.  For example, if the current client is forbidden
   from posting, then this will apply equally to groups with status "y".
   Conversely, a client with special privileges (not defined by this
   specification) might be able to post to a group with status "n".

   For example:

      [C] LIST ACTIVE
      [S] 215 list of newsgroups follows
      [S] misc.test 3002322 3000234 y
      [S] comp.risks 442001 441099 m
      [S] alt.rfc-writers.recovery 4 1 y
      [S] tx.natives.recovery 89 56 y
      [S] tx.natives.recovery.d 11 9 n
      [S] .

   or, on an implementation that includes leading zeroes:

      [C] LIST ACTIVE
      [S] 215 list of newsgroups follows
      [S] misc.test 0003002322 0003000234 y
      [S] comp.risks 0000442001 0000441099 m
      [S] alt.rfc-writers.recovery 0000000004 0000000001 y
      [S] tx.natives.recovery 0000000089 0000000056 y
      [S] tx.natives.recovery.d 0000000011 0000000009 n
      [S] .

   The information is newsgroup based, and a wildmat MAY be specified,
   in which case the response is limited to only the groups (if any)
   whose names match the wildmat.  For example:

      [C] LIST ACTIVE *.recovery
      [S] 215 list of newsgroups follows
      [S] alt.rfc-writers.recovery 4 1 y
      [S] tx.natives.recovery 89 56 y
      [S] .

7.6.4.  LIST ACTIVE.TIMES

   This keyword is optional.

   The active.times list is maintained by some NNTP servers to contain
   information about who created a particular newsgroup and when.  Each
   line of this list consists of three fields separated from each other
   by one or more spaces.  The first field is the name of the newsgroup.
   The second is the time when this group was created on this news
   server, measured in seconds since the start of January 1, 1970.  The
   third is plain text intended to describe the entity that created the
   newsgroup; it is often a mailbox as defined in RFC 2822 [RFC2822].
   For example:

      [C] LIST ACTIVE.TIMES
      [S] 215 information follows
      [S] misc.test 930445408 <creatme@isc.org>
      [S] alt.rfc-writers.recovery 930562309 <m@example.com>
      [S] tx.natives.recovery 930678923 <sob@academ.com>
      [S] .

   The list MAY omit newsgroups for which the information is unavailable
   and MAY include groups not available on the server; in particular, it
   MAY omit all groups created before the date and time of the oldest
   entry.  The client MUST NOT assume that the list is complete or that
   it matches the list returned by the LIST ACTIVE command
   (Section 7.6.3).  The NEWGROUPS command (Section 7.3) may provide a
   better way to access this information, and the results of the two
   commands SHOULD be consistent except that, if the latter is invoked
   with a date and time earlier than the oldest entry in active.times
   list, its result may include extra groups.

   The information is newsgroup based, and a wildmat MAY be specified,
   in which case the response is limited to only the groups (if any)
   whose names match the wildmat.

7.6.5.  LIST DISTRIB.PATS

   This keyword is optional.

   The distrib.pats list is maintained by some NNTP servers to assist
   clients to choose a value for the content of the Distribution header
   of a news article being posted.  Each line of this list consists of
   three fields separated from each other by a colon (":").  The first
   field is a weight, the second field is a wildmat (which may be a
   simple newsgroup name), and the third field is a value for the
   Distribution header content.  For example:

      [C] LIST DISTRIB.PATS
      [S] 215 information follows
      [S] 10:local.*:local
      [S] 5:*:world
      [S] 20:local.here.*:thissite
      [S] .

   The client MAY use this information to construct an appropriate
   Distribution header given the name of a newsgroup.  To do so, it
   should determine the lines whose second field matches the newsgroup
   name, select from among them the line with the highest weight (with 0
   being the lowest), and use the value of the third field to construct
   the Distribution header.

   The information is not newsgroup based, and an argument MUST NOT be
   specified.

7.6.6.  LIST NEWSGROUPS

   This keyword MUST be supported by servers advertising the READER
   capability.

   The newsgroups list is maintained by NNTP servers to contain the name
   of each newsgroup that is available on the server and a short
   description about the purpose of the group.  Each line of this list
   consists of two fields separated from each other by one or more space
   or TAB characters (the usual practice is a single TAB).  The first
   field is the name of the newsgroup, and the second is a short
   description of the group.  For example:

      [C] LIST NEWSGROUPS
      [S] 215 information follows
      [S] misc.test General Usenet testing
      [S] alt.rfc-writers.recovery RFC Writers Recovery
      [S] tx.natives.recovery Texas Natives Recovery
      [S] .

   The list MAY omit newsgroups for which the information is unavailable
   and MAY include groups not available on the server.  The client MUST
   NOT assume that the list is complete or that it matches the list
   returned by LIST ACTIVE.

   The description SHOULD be in UTF-8.  However, servers often obtain
   the information from external sources.  These sources may have used
   different encodings (ones that use octets in the range 128 to 255 in
   some other manner) and, in that case, the server MAY pass it on
   unchanged.  Therefore, clients MUST be prepared to receive such
   descriptions.

   The information is newsgroup based, and a wildmat MAY be specified,
   in which case the response is limited to only the groups (if any)
   whose names match the wildmat.

8.  Article Field Access Commands

   This section lists commands that may be used to access specific
   article fields; that is, headers of articles and metadata about
   articles.  These commands typically fetch data from an "overview
   database", which is a database of headers extracted from incoming
   articles plus metadata determined as the article arrives.  Only
   certain fields are included in the database.

   This section is based on the Overview/NOV database [ROBE1995]
   developed by Geoff Collyer.

8.1.  Article Metadata

   Article "metadata" is data about articles that does not occur within
   the article itself.  Each metadata item has a name that MUST begin
   with a colon (and that MUST NOT contain a colon elsewhere within it).
   As with header names, metadata item names are not case sensitive.

   When generating a metadata item, the server MUST compute it for
   itself and MUST NOT trust any related value provided in the article.
   (In particular, a Lines or Bytes header in the article MUST NOT be
   assumed to specify the correct number of lines or bytes in the
   article.)  If the server has access to several non-identical copies
   of an article, the value returned MUST be correct for any copy of
   that article retrieved during the same session.

   This specification defines two metadata items: ":bytes" and ":lines".
   Other metadata items may be defined by extensions.  The names of
   metadata items defined by registered extensions MUST NOT begin with
   ":x-".  To avoid the risk of a clash with a future registered
   extension, the names of metadata items defined by private extensions
   SHOULD begin with ":x-".

8.1.1.  The :bytes Metadata Item

   The :bytes metadata item for an article is a decimal integer.  It
   SHOULD equal the number of octets in the entire article: headers,
   body, and separating empty line (counting a CRLF pair as two octets,
   and excluding both the "." CRLF terminating the response and any "."
   added for "dot-stuffing" purposes).

   Note to client implementers: some existing servers return a value
   different from that above.  The commonest reasons for this are as
   follows:

   o  Counting a CRLF pair as one octet.

   o  Including the "." character used for dot-stuffing in the number.

   o  Including the terminating "." CRLF in the number.

   o  Using one copy of an article for counting the octets but then
      returning another one that differs in some (permitted) manner.

   Implementations should be prepared for such variation and MUST NOT
   rely on the value being accurate.

8.1.2.  The :lines Metadata Item

   The :lines metadata item for an article is a decimal integer.  It
   MUST equal the number of lines in the article body (excluding the
   empty line separating headers and body).  Equivalently, it is two
   less than the number of CRLF pairs that the BODY command would return
   for that article (the extra two are those following the response code
   and the termination octet).

8.2.  Database Consistency

   The information stored in the overview database may change over time.
   If the database records the content or absence of a given field (that
   is, a header or metadata item) for all articles, it is said to be
   "consistent" for that field.  If it records the content of a header
   for some articles but not for others that nevertheless included that
   header, or if it records a metadata item for some articles but not
   for others to which that item applies, it is said to be
   "inconsistent" for that field.

   The LIST OVERVIEW.FMT command SHOULD list all the fields for which
   the database is consistent at that moment.  It MAY omit such fields
   (for example, if it is not known whether the database is consistent
   or inconsistent).  It MUST NOT include fields for which the database
   is inconsistent or that are not stored in the database.  Therefore,
   if a header appears in the LIST OVERVIEW.FMT output but not in the
   OVER output for a given article, that header does not appear in the
   article (similarly for metadata items).

   These rules assume that the fields being stored in the database
   remain constant for long periods of time, and therefore the database
   will be consistent.  When the set of fields to be stored is changed,
   it will be inconsistent until either the database is rebuilt or the
   only articles remaining are those received since the change.
   Therefore, the output from LIST OVERVIEW.FMT needs to be altered
   twice.  Firstly, before any fields stop being stored they MUST be
   removed from the output; then, when the database is once more known
   to be consistent, the new fields SHOULD be added to the output.

   If the HDR command uses the overview database rather than taking
   information directly from the articles, the same issues of
   consistency and inconsistency apply, and the LIST HEADERS command
   SHOULD take the same approach as the LIST OVERVIEW.FMT command in
   resolving them.

8.3.  OVER

8.3.1.  Usage

   Indicating capability: OVER

   Syntax
     OVER message-id
     OVER range
     OVER

   Responses

   First form (message-id specified)
     224    Overview information follows (multi-line)
     430    No article with that message-id

   Second form (range specified)
     224    Overview information follows (multi-line)
     412    No newsgroup selected
     423    No articles in that range

   Third form (current article number used)
     224    Overview information follows (multi-line)
     412    No newsgroup selected
     420    Current article number is invalid

   Parameters
     range         Number(s) of articles
     message-id    Message-id of article

8.3.2.  Description

   The OVER command returns the contents of all the fields in the
   database for an article specified by message-id, or from a specified
   article or range of articles in the currently selected newsgroup.

   The message-id argument indicates a specific article.  The range
   argument may be any of the following:

   o  An article number.

   o  An article number followed by a dash to indicate all following.

   o  An article number followed by a dash followed by another article
      number.

   If neither is specified, the current article number is used.

   Support for the first (message-id) form is optional.  If it is
   supported, the OVER capability line MUST include the argument
   "MSGID".  Otherwise, the capability line MUST NOT include this
   argument, and the OVER command MUST return the generic response code
   503 when this form is used.

   If the information is available, it is returned as a multi-line data
   block following the 224 response code and contains one line per
   article, sorted in numerical order of article number.  (Note that
   unless the argument is a range including a dash, there will be
   exactly one line in the data block.)  Each line consists of a number
   of fields separated by a TAB.  A field may be empty (in which case
   there will be two adjacent TABs), and a sequence of trailing TABs may
   be omitted.

   The first 8 fields MUST be the following, in order:

      "0" or article number (see below)
      Subject header content
      From header content
      Date header content
      Message-ID header content
      References header content
      :bytes metadata item
      :lines metadata item

   If the article is specified by message-id (the first form of the
   command), the article number MUST be replaced with zero, except that
   if there is a currently selected newsgroup and the article is present
   in that group, the server MAY use the article's number in that group.
   (See the ARTICLE command (Section 6.2.1) and STAT examples
   (Section 6.2.4.3) for more details.)  In the other two forms of the
   command, the article number MUST be returned.

   Any subsequent fields are the contents of the other headers and
   metadata held in the database.

   For the five mandatory headers, the content of each field MUST be
   based on the content of the header (that is, with the header name and
   following colon and space removed).  If the article does not contain
   that header, or if the content is empty, the field MUST be empty.
   For the two mandatory metadata items, the content of the field MUST
   be just the value, with no other text.

   For all subsequent fields that contain headers, the content MUST be
   the entire header line other than the trailing CRLF.  For all
   subsequent fields that contain metadata, the field consists of the
   metadata name, a single space, and then the value.

   For all fields, the value is processed by first removing all CRLF
   pairs (that is, undoing any folding and removing the terminating
   CRLF) and then replacing each TAB with a single space.  If there is
   no such header in the article, no such metadata item, or no header or
   item stored in the database for that article, the corresponding field
   MUST be empty.

   Note that, after unfolding, the characters NUL, LF, and CR cannot
   occur in the header of an article offered by a conformant server.
   Nevertheless, servers SHOULD check for these characters and replace
   each one by a single space (so that, for example, CR LF LF TAB will
   become two spaces, since the CR and first LF will be removed by the
   unfolding process).  This will encourage robustness in the face of
   non-conforming data; it is also possible that future versions of this
   specification could permit these characters to appear in articles.

   The server SHOULD NOT produce output for articles that no longer
   exist.

   If the argument is a message-id and no such article exists, a 430
   response MUST be returned.  If the argument is a range or is omitted
   and the currently selected newsgroup is invalid, a 412 response MUST
   be returned.  If the argument is a range and no articles in that
   number range exist in the currently selected newsgroup, including the
   case where the second number is less than the first one, a 423
   response MUST be returned.  If the argument is omitted and the
   current article number is invalid, a 420 response MUST be returned.

8.3.3.  Examples

   In the first four examples, TAB has been replaced by vertical bar and
   some lines have been folded for readability.

   Example of a successful retrieval of overview information for an
   article (explicitly not using an article number):

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] OVER
      [S] 224 Overview information follows
      [S] 3000234|I am just a test article|"Demo User"
          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
          <45223423@example.com>|<45454@example.net>|1234|
          17|Xref: news.example.com misc.test:3000363
      [S] .

   Example of a successful retrieval of overview information for an
   article by message-id:

      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] OVER MSGID
      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
      [S] .
      [C] OVER <45223423@example.com>
      [S] 224 Overview information follows
      [S] 0|I am just a test article|"Demo User"
          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
          <45223423@example.com>|<45454@example.net>|1234|
          17|Xref: news.example.com misc.test:3000363
      [S] .

   Note that the article number has been replaced by "0".

   Example of the same commands on a system that does not implement
   retrieval by message-id:

      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] OVER
      [S] LIST ACTIVE NEWSGROUPS OVERVIEW.FMT
      [S] .
      [C] OVER <45223423@example.com>
      [S] 503 Overview by message-id unsupported

   Example of a successful retrieval of overview information for a range
   of articles:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] OVER 3000234-3000240
      [S] 224 Overview information follows
      [S] 3000234|I am just a test article|"Demo User"
          <nobody@example.com>|6 Oct 1998 04:38:40 -0500|
          <45223423@example.com>|<45454@example.net>|1234|
          17|Xref: news.example.com misc.test:3000363
      [S] 3000235|Another test article|nobody@nowhere.to
          (Demo User)|6 Oct 1998 04:38:45 -0500|<45223425@to.to>||
          4818|37||Distribution: fi
      [S] 3000238|Re: I am just a test article|somebody@elsewhere.to|
          7 Oct 1998 11:38:40 +1200|<kfwer3v@elsewhere.to>|
          <45223423@to.to>|9234|51
      [S] .

   Note the missing "References" and Xref headers in the second line,
   the missing trailing fields in the first and last lines, and that
   there are only results for those articles that still exist.

   Example of an unsuccessful retrieval of overview information on an
   article by number:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] OVER 300256
      [S] 423 No such article in this group

   Example of an invalid range:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] OVER 3000444-3000222
      [S] 423 Empty range

   Example of an unsuccessful retrieval of overview information by
   number because no newsgroup was selected first:

      [Assumes currently selected newsgroup is invalid.]
      [C] OVER
      [S] 412 No newsgroup selected

   Example of an attempt to retrieve information when the currently
   selected newsgroup is empty:

      [C] GROUP example.empty.newsgroup
      [S] 211 0 0 0 example.empty.newsgroup
      [C] OVER
      [S] 420 No current article selected

8.4.  LIST OVERVIEW.FMT

8.4.1.  Usage

   Indicating capability: OVER

   Syntax
     LIST OVERVIEW.FMT

   Responses
     215    Information follows (multi-line)

8.4.2.  Description

   See Section 7.6.1 for general requirements of the LIST command.

   The LIST OVERVIEW.FMT command returns a description of the fields in
   the database for which it is consistent (as described above).  The
   information is returned as a multi-line data block following the 215
   response code.  The information contains one line per field in the
   order in which they are returned by the OVER command; the first 7
   lines MUST (except for the case of letters) be exactly as follows:

       Subject:
       From:
       Date:
       Message-ID:
       References:
       :bytes
       :lines

   For compatibility with existing implementations, the last two lines
   MAY instead be:

       Bytes:
       Lines:

   even though they refer to metadata, not headers.

   All subsequent lines MUST consist of either a header name followed by
   ":full", or the name of a piece of metadata.

   There are no leading or trailing spaces in the output.

   Note that the 7 fixed lines describe the 2nd to 8th fields of the
   OVER output.  The "full" suffix (which may use either uppercase,
   lowercase, or a mix) is a reminder that the corresponding fields
   include the header name.

   This command MAY generate different results if it is used more than
   once in a session.

   If the OVER command is not implemented, the meaning of the output
   from this command is not specified, but it must still meet the above
   syntactic requirements.

8.4.3.  Examples

   Example of LIST OVERVIEW.FMT output corresponding to the example OVER
   output above, in the preferred format:

      [C] LIST OVERVIEW.FMT
      [S] 215 Order of fields in overview database.
      [S] Subject:
      [S] From:
      [S] Date:
      [S] Message-ID:
      [S] References:
      [S] :bytes
      [S] :lines
      [S] Xref:full
      [S] Distribution:full
      [S] .

   Example of LIST OVERVIEW.FMT output corresponding to the example OVER
   output above, in the alternative format:

      [C] LIST OVERVIEW.FMT
      [S] 215 Order of fields in overview database.
      [S] Subject:
      [S] From:
      [S] Date:
      [S] Message-ID:
      [S] References:
      [S] Bytes:
      [S] Lines:
      [S] Xref:FULL
      [S] Distribution:FULL
      [S] .

8.5.  HDR

8.5.1.  Usage

   Indicating capability: HDR

   Syntax
     HDR field message-id
     HDR field range
     HDR field

   Responses

   First form (message-id specified)
     225    Headers follow (multi-line)
     430    No article with that message-id

   Second form (range specified)
     225    Headers follow (multi-line)
     412    No newsgroup selected
     423    No articles in that range

   Third form (current article number used)
     225    Headers follow (multi-line)
     412    No newsgroup selected
     420    Current article number is invalid

   Parameters
     field         Name of field
     range         Number(s) of articles
     message-id    Message-id of article

8.5.2.  Description

   The HDR command provides access to specific fields from an article
   specified by message-id, or from a specified article or range of
   articles in the currently selected newsgroup.  It MAY take the
   information directly from the articles or from the overview database.
   In the case of headers, an implementation MAY restrict the use of
   this command to a specific list of headers or MAY allow it to be used
   with any header; it may behave differently when it is used with a
   message-id argument and when it is used with a range or no argument.

   The required field argument is the name of a header with the colon
   omitted (e.g., "subject") or the name of a metadata item including
   the leading colon (e.g., ":bytes"), and is case insensitive.

   The message-id argument indicates a specific article.  The range
   argument may be any of the following:

   o  An article number.

   o  An article number followed by a dash to indicate all following.

   o  An article number followed by a dash followed by another article
      number.

   If neither is specified, the current article number is used.

   If the information is available, it is returned as a multi-line data
   block following the 225 response code and contains one line for each
   article in the range that exists.  (Note that unless the argument is
   a range including a dash, there will be exactly one line in the data
   block.)  The line consists of the article number, a space, and then
   the contents of the field.  In the case of a header, the header name,
   the colon, and the first space after the colon are all omitted.

   If the article is specified by message-id (the first form of the
   command), the article number MUST be replaced with zero, except that
   if there is a currently selected newsgroup and the article is present
   in that group, the server MAY use the article's number in that group.
   (See the ARTICLE command (Section 6.2.1) and STAT examples
   (Section 6.2.4.3) for more details.)  In the other two forms of the
   command, the article number MUST be returned.

   Header contents are modified as follows: all CRLF pairs are removed,
   and then each TAB is replaced with a single space.  (Note that this
   is the same transformation as is performed by the OVER command
   (Section 8.3.2), and the same comment concerning NUL, CR, and LF
   applies.)

   Note the distinction between headers and metadata appearing to have
   the same meaning.  Headers are always taken unchanged from the
   article; metadata are always calculated.  For example, a request for
   "Lines" returns the contents of the "Lines" header of the specified
   articles, if any, no matter whether they accurately state the number
   of lines, while a request for ":lines" returns the line count
   metadata, which is always the actual number of lines irrespective of
   what any header may state.

   If the requested header is not present in the article, or if it is
   present but empty, a line for that article is included in the output,
   but the header content portion of the line is empty (the space after
   the article number MAY be retained or omitted).  If the header occurs
   in a given article more than once, only the content of the first
   occurrence is returned by HDR.  If any article number in the provided
   range does not exist in the group, no line for that article number is
   included in the output.

   If the second argument is a message-id and no such article exists, a
   430 response MUST be returned.  If the second argument is a range or
   is omitted and the currently selected newsgroup is invalid, a 412
   response MUST be returned.  If the second argument is a range and no
   articles in that number range exist in the currently selected
   newsgroup, including the case where the second number is less than
   the first one, a 423 response MUST be returned.  If the second
   argument is omitted and the current article number is invalid, a 420
   response MUST be returned.

   A server MAY only allow HDR commands for a limited set of fields; it
   may behave differently in this respect for the first (message-id)
   form from how it would for the other forms.  If so, it MUST respond
   with the generic 503 response to attempts to request other fields,
   rather than return erroneous results, such as a successful empty
   response.

   If HDR uses the overview database and it is inconsistent for the
   requested field, the server MAY return what results it can, or it MAY
   respond with the generic 503 response.  In the latter case, the field
   MUST NOT appear in the output from LIST HEADERS.

8.5.3.  Examples

   Example of a successful retrieval of subject lines from a range of
   articles (3000235 has no Subject header, and 3000236 is missing):

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR Subject 3000234-3000238
      [S] 225 Headers follow
      [S] 3000234 I am just a test article
      [S] 3000235
      [S] 3000237 Re: I am just a test article
      [S] 3000238 Ditto
      [S] .

   Example of a successful retrieval of line counts from a range of
   articles:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR :lines 3000234-3000238
      [S] 225 Headers follow
      [S] 3000234 42
      [S] 3000235 5
      [S] 3000237 11
      [S] 3000238 2378
      [S] .

   Example of a successful retrieval of the subject line from an article
   by message-id:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR subject <i.am.a.test.article@example.com>
      [S] 225 Header information follows
      [S] 0 I am just a test article
      [S] .

   Example of a successful retrieval of the subject line from the
   current article:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR subject
      [S] 225 Header information follows
      [S] 3000234 I am just a test article
      [S] .

   Example of an unsuccessful retrieval of a header from an article by
   message-id:

      [C] HDR subject <i.am.not.there@example.com>
      [S] 430 No Such Article Found

   Example of an unsuccessful retrieval of headers from articles by
   number because no newsgroup was selected first:

      [Assumes currently selected newsgroup is invalid.]
      [C] HDR subject 300256-
      [S] 412 No newsgroup selected

   Example of an unsuccessful retrieval of headers because the currently
   selected newsgroup is empty:

      [C] GROUP example.empty.newsgroup
      [S] 211 0 0 0 example.empty.newsgroup
      [C] HDR subject 1-
      [S] 423 No articles in that range

   Example of an unsuccessful retrieval of headers because the server
   does not allow HDR commands for that header:

      [C] GROUP misc.test
      [S] 211 1234 3000234 3002322 misc.test
      [C] HDR Content-Type 3000234-3000238
      [S] 503 HDR not permitted on Content-Type

8.6.  LIST HEADERS

8.6.1.  Usage

   Indicating capability: HDR

   Syntax
     LIST HEADERS [MSGID|RANGE]

   Responses
     215    Field list follows (multi-line)

   Parameters
     MSGID    Requests list for access by message-id
     RANGE    Requests list for access by range

8.6.2.  Description

   See Section 7.6.1 for general requirements of the LIST command.

   The LIST HEADERS command returns a list of fields that may be
   retrieved using the HDR command.

   The information is returned as a multi-line data block following the
   215 response code and contains one line for each field name
   (excluding the trailing colon for headers and including the leading
   colon for metadata items).  If the implementation allows any header
   to be retrieved, it MUST NOT include any header names in the list but
   MUST include the special entry ":" (a single colon on its own).  It
   MUST still explicitly list any metadata items that are available.
   The order of items in the list is not significant; the server need
   not even consistently return the same order.  The list MAY be empty
   (though in this circumstance there is little point in providing the
   HDR command).

   An implementation that also supports the OVER command SHOULD at least
   permit all the headers and metadata items listed in the output from
   the LIST OVERVIEW.FMT command.

   If the server treats the first form of the HDR command (message-id
   specified) differently from the other two forms (range specified or
   current article number used) in respect of which headers or metadata
   items are available, then the following apply:

   o  If the MSGID argument is specified, the results MUST be those
      available for the first form of the HDR command.

   o  If the RANGE argument is specified, the results MUST be those
      available for the second and third forms of the HDR command.

   o  If no argument is specified, the results MUST be those available
      in all forms of the HDR command (that is, it MUST only list those
      items listed in both the previous cases).

   If the server does not treat the various forms differently, then it
   MUST ignore any argument and always produce the same results (though
   not necessarily always in the same order).

   If the HDR command is not implemented, the meaning of the output from
   this command is not specified, but it must still meet the above
   syntactic requirements.

8.6.3.  Examples

   Example of an implementation providing access to only a few headers:

      [C] LIST HEADERS
      [S] 215 headers supported:
      [S] Subject
      [S] Message-ID
      [S] Xref
      [S] .

   Example of an implementation providing access to the same fields as
   the first example in Section 8.4.3:

      [C] CAPABILITIES
      [S] 101 Capability list:
      [S] VERSION 2
      [S] READER
      [S] OVER
      [S] HDR
      [S] LIST ACTIVE NEWSGROUPS HEADERS OVERVIEW.FMT
      [S] .
      [C] LIST HEADERS
      [S] 215 headers and metadata items supported:
      [S] Date
      [S] Distribution
      [S] From
      [S] Message-ID
      [S] References
      [S] Subject
      [S] Xref
      [S] :bytes
      [S] :lines
      [S] .

   Example of an implementation providing access to all headers:

      [C] LIST HEADERS
      [S] 215 metadata items supported:
      [S] :
      [S] :lines
      [S] :bytes
      [S] :x-article-number
      [S] .

   Example of an implementation distinguishing the first form of the HDR
   command from the other two forms:

      [C] LIST HEADERS RANGE
      [S] 215 metadata items supported:
      [S] :
      [S] :lines
      [S] :bytes
      [S] .
      [C] LIST HEADERS MSGID
      [S] 215 headers and metadata items supported:
      [S] Date
      [S] Distribution
      [S] From
      [S] Message-ID
      [S] References
      [S] Subject
      [S] :lines
      [S] :bytes
      [S] :x-article-number
      [S] .
      [C] LIST HEADERS
      [S] 215 headers and metadata items supported:
      [S] Date
      [S] Distribution
      [S] From
      [S] Message-ID
      [S] References
      [S] Subject
      [S] :lines
      [S] :bytes
      [S] .

   Note that :x-article-number does not appear in the last set of
   output.