Tech-invite3GPPspaceIETFspace
959493929190898887868584838281807978777675747372717069686766656463626160595857565554535251504948474645444342414039383736353433323130292827262524232221201918171615141312111009080706050403020100
in Index   Prev   Next

RFC 3977

Network News Transfer Protocol (NNTP)

Pages: 125
Proposed Standard
Errata
Obsoletes:  0977
Updates:  2980
Updated by:  6048
Part 3 of 4 – Pages 61 to 90
First   Prev   Next

Top   ToC   RFC3977 - Page 61   prevText

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
Top   ToC   RFC3977 - Page 62
   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.
Top   ToC   RFC3977 - Page 63
   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.
Top   ToC   RFC3977 - Page 64
   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
Top   ToC   RFC3977 - Page 65

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.
Top   ToC   RFC3977 - Page 66
   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.
Top   ToC   RFC3977 - Page 67

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.
Top   ToC   RFC3977 - Page 68
   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] .
Top   ToC   RFC3977 - Page 69
   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 | +--------------+---------------+------------------------------------+
Top   ToC   RFC3977 - Page 70
   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".
Top   ToC   RFC3977 - Page 71
   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:
Top   ToC   RFC3977 - Page 72
      [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.
Top   ToC   RFC3977 - Page 73
   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.
Top   ToC   RFC3977 - Page 74
   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.
Top   ToC   RFC3977 - Page 75

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.
Top   ToC   RFC3977 - Page 76

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.
Top   ToC   RFC3977 - Page 77
   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.
Top   ToC   RFC3977 - Page 78
   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] .
Top   ToC   RFC3977 - Page 79
   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
Top   ToC   RFC3977 - Page 80
   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
Top   ToC   RFC3977 - Page 81
   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.
Top   ToC   RFC3977 - Page 82
   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] .
Top   ToC   RFC3977 - Page 83
   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
Top   ToC   RFC3977 - Page 84

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.)
Top   ToC   RFC3977 - Page 85
   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.
Top   ToC   RFC3977 - Page 86

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] .
Top   ToC   RFC3977 - Page 87
   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
Top   ToC   RFC3977 - Page 88

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.
Top   ToC   RFC3977 - Page 89

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] .
Top   ToC   RFC3977 - Page 90
   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.



(page 90 continued on part 4)

Next Section