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