NAME

       nntp - Tcl client for the NNTP protocol


SYNOPSIS

       package require nntp ?0.1?

       ::nntp::nntp ?host? ?port? ?nntpName?

_________________________________________________________________


DESCRIPTION

       The nntp package provides a simple Tcl-only client library
       for the NNTP protocol.  It works by opening  the  standard
       NNTP socket on the server, and then providing a Tcl API to
       access the NNTP protocol commands.  All server errors  are
       returned  as Tcl errors (thrown) which must be caught with
       the Tcl catch command.  The ::nntp::nntp command creates a
       new  nntp object with an associated Tcl command whose name
       is returned by the ::nntp::nntp command (nntpName).   This
       command  may  be  used to access the various NNTP protocol
       commands.  Some of the commands supported by this  package
       are  not  part  of  the nntp rfc (rfc 977) and will not be
       available (or implemented) on all nntp servers.  The  com­
       mands have the following general form:
              nntpName option ?arg arg ...?
       Option  and  the  args determine the exact behavior of the
       command.


COMMANDS

       ::nntp::nntp ?host? ?port? ?nntpName?
              Open a socket connection to  a  NNTP  server.   The
              command returns the name of the global command that
              can be used to access the  nntp  connection  subse­
              quently.   The  default  port number is 119 and the
              default server is news which can be overridden with
              the  environment  variables  NNTPPORT  and NNTPHOST
              respectively.

       nntpName article ?msgid?
              Query the server for article msgid from the current
              group.  The article is returned as a valid tcl list
              which contains the headers,  followed  by  a  blank
              line, and then followed by the body of the article.
              Each element in the list is one line of  the  arti­
              cle.

       nntpName authinfo ?user? ?pass?
              Send authentication information (username and pass­
              word) to the server.

              Query the server for the body of the article  msgid
              from the current group.  The body of the article is
              returned as a valid tcl list. Each element  in  the
              list is one line of the body of the article.

       nntpName date
              Query the server for the servers current date.  The
              date is returned in the format YYYYMMDDHHMMSS

       nntpName group ?group?
              Optionally set  the  current  group,  and  retrieve
              information  about  the  currently  selected group.
              Returns the estimated number  of  articles  in  the
              group  followed  by the number of the first article
              in the group, followed by the last article  in  the
              group, followed by the name of the group.

       nntpName head ?msgid?
              Query  the  server  for  the headers of the article
              msgid from the current group.  The headers  of  the
              article are returned as a valid tcl list. Each ele­
              ment in the list is one line of the headers of  the
              article.

       nntpName help
              Retrieves a list of the commands that are supported
              by the news server that is currently attached to.

       nntpName last
              Sets the current article pointer to  point  to  the
              previous  message (if there is one) and returns the
              msgid of that message.

       nntpName list
              Returns a tcl list of valid newsgroups and  associ­
              ated information.  Each newsgroup is returned as an
              element in the tcl list with the following format:

                    group last first p

              where <group> is the name of the newsgroup,  <last>
              is  the  number of the last known article currently
              in that newsgroup, <first> is  the  number  of  the
              first  article  currently in the newsgroup, and <p>
              is either 'y' or 'n' indicating whether posting  to
              this  newsgroup  is  allowed  ('y')  or  prohibited
              ('n').

              The  <first>  and  <last>  fields  will  always  be
              numeric.   They  may  have  leading  zeros.  If the
              <last> field evaluates to  less  than  the  <first>
              field,  there  are no articles currently on file in
              the newsgroup.

              Query the server for a list  of  all  the  messages
              (message  numbers)  in  the  group specified by the
              argument group or by the current group if the group
              argument was not passed.

       nntpName mode_reader
              Query   the  server  for  its  nntp  'MODE  READER'
              response string.

       nntpName newgroups since
              Query the server for a list of all  the  new  news­
              groups  created  since  the  time  specified by the
              argument since.  The argument since can be any time
              string  that  is  understood by clock scan. The tcl
              list of newsgroups is returned in a similar form to
              the  list  of  groups returned by the nntpName list
              command.  Each element of the list has the form:

                    group last first p

              where <group> is the name of the newsgroup,  <last>
              is  the  number of the last known article currently
              in that newsgroup, <first> is  the  number  of  the
              first  article  currently in the newsgroup, and <p>
              is either 'y' or 'n' indicating whether posting  to
              this  newsgroup  is  allowed  ('y')  or  prohibited
              ('n').

       nntpName newnews
              Query the server for a list of new articles  posted
              to the current group in the last day.

       nntpName newnews since
              Query  the server for a list of new articles posted
              to the current group since the  time  specified  by
              the  argument since.  The argument since can be any
              time string that is understood by clock scan.

       nntpName newnews group ?since?
              Query the server for a list of new articles  posted
              to  the group specified by the argument group since
              the time specified by the argument since (or in the
              past day if no since argument is passed.  The argu­
              ment since can be any time string  that  is  under­
              stood by clock scan.

       nntpName next
              Sets  the  current  article pointer to point to the
              next message (if there  is  one)  and  returns  the
              msgid of that message.

       nntpName post article
              Posts  an  article of the form specified in RFC 850


       nntpName slave
              Identifies a connection as being made from a  slave
              nntp  server.  This  might be used to indicate that
              the  connection  is  serving  multiple  people  and
              should  be  given priority.  Actual use is entirely
              implementation dependent and may vary  from  server
              to server.

       nntpName stat ?msgid?
              The  stat command is similar to the article command
              except that no text is returned.  When selecting by
              message  number  within  a  group, the stat command
              serves to set the current article  pointer  without
              sending  text. The returned acknowledgment response
              will contain the message-id, which may be  of  some
              value.   Using  the  stat command to select by mes­
              sage-id is valid but of questionable value, since a
              selection by message-id does NOT alter the "current
              article pointer"

       nntpName quit
              Gracefully close the  connection  after  sending  a
              NNTP QUIT command down the socket.

       nntpName xgtitle ?group_pattern?
              Returns  a  tcl  list  where each element is of the
              form:

              newsgroup description

              If a group_pattern is  specified  then  only  news­
              groups  that match the pattern will have their name
              and description returned.

       nntpName xhdr field ?range?
              Returns the specified header field  value  for  the
              current  message or for a list of messages from the
              current group.  field is the title of  a  field  in
              the  header  such  as from, subject, date, etc.  If
              range is not specified or is ""  then  the  current
              message  is queried.  The command returns a list of
              elements where each element has the form of:

              msgid value

              Where msgid is the number of the message and  value
              is  the value set for the queried field.  The range
              argument can be in any of the following forms:

              ""     The current message is queried.

                     All  messages  between  msgid1  and   msgid2
                     (including msgid1 and msgid2) are queried.

              msgid1 msgid2
                     All   messages  between  msgid1  and  msgid2
                     (including msgid1 and msgid2) are queried.

       nntpName xover ?range?
              Returns header information for the current  message
              or  for a range of messages from the current group.
              The information is returned in  a  tcl  list  where
              each element is of the form:

              msgid  subject  from date idstring bodysize header­
              size xref

              If range is not specified or is "" then the current
              message  is  queried.  The range argument can be in
              any of the following forms:

              ""     The current message is queried.

              msgid1-msgid2
                     All  messages  between  msgid1  and   msgid2
                     (including msgid1 and msgid2) are queried.

              msgid1 msgid2
                     All   messages  between  msgid1  and  msgid2
                     (including msgid1 and msgid2) are queried.

       nntpName xpat field range ?pattern_list?
              Returns the specified  header  field  value  for  a
              specified  message  or  for a list of messages from
              the current group where the messages match the pat­
              tern(s)  given  in  the pattern_list.  field is the
              title of a field in the header such as  from,  sub­
              ject,  date, etc.  The information is returned in a
              tcl list where each element is of the form:

              msgid value

              Where msgid is the number of the message and  value
              is  the value set for the queried field.  The range
              argument can be in any of the following forms:

              msgid  The message specified by msgid is queried.

              msgid1-msgid2
                     All  messages  between  msgid1  and   msgid2
                     (including msgid1 and msgid2) are queried.

              msgid1 msgid2
                     All   messages  between  msgid1  and  msgid2


       KEYWORDS
              news, nntp, nntpclient


Man(1) output converted with man2html