home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / slurp108.zip / slurp.man < prev    next >
Text File  |  1995-09-04  |  11KB  |  331 lines
  1.  
  2.  
  3.  
  4. SLURP(1)                                                 SLURP(1)
  5.  
  6.  
  7. NAME
  8.        slurp  -  retrieve  netnews  articles  from  a remote NNTP
  9.        server
  10.  
  11.  
  12. SYNOPSIS
  13.        slurp [ -g newsgroups/distributions ] [ -t  time  ]  [  -a
  14.        username/password  ]  [  -d  ] [ -i ] [ -l ] [ -r ] [ -w ]
  15.        hostname[ /sublist ][ :timefile ]
  16.  
  17.  
  18. DESCRIPTION
  19.        Slurp is an advanced passive NNTP client for UNIX. It will
  20.        connect to a remote NNTP server and retrieve articles in a
  21.        specified set of Usenet newsgroups that have arrived after
  22.        a particular time (typically the last time it was invoked)
  23.        for processing by your local news system.
  24.  
  25.  
  26. OPTIONS
  27.        -g newsgroups/distributions
  28.               If specified then overrides any newsgroups and dis-
  29.               tributions   specification   for  hostname  in  the
  30.               slurp.sys file.
  31.  
  32.        -t time
  33.               Retrieve articles that have arrived at  the  server
  34.               after  time  rather  than using the time taken from
  35.               slurp.<hostname>.  This is  in  the  standard  NNTP
  36.               time  format  of  'YYMMDD HHMMSS' GMT. For example,
  37.               midnight GMT on the 1st of December  1992  will  be
  38.               '921201  000000'.  Note  that  you will need to use
  39.               quotes around the time and remember that  the  time
  40.               is in GMT, not the local or server time.
  41.  
  42.        -a username/password
  43.               If  specified then the username and password combi-
  44.               nation will be sent to the server as  part  of  the
  45.               simple  authorisation  protocol when the connection
  46.               is first made.
  47.  
  48.        -d     Enable debugging. This diverts reporting to  stderr
  49.               instead of syslog and turns on extra debugging out-
  50.               put.
  51.  
  52.        -i     Normally if an error occurs while fetching articles
  53.               from  the  server,  the remaining message IDs to be
  54.               fetched are written  to  slurp.<hostname>  so  that
  55.               they  may  be retrieved in the next session without
  56.               having to restart the NEWNEWS at  the  same  point.
  57.               With  this  option selected, no message IDs will be
  58.               read from slurp.<hostname> and in the event  of  an
  59.               error   occurring,  slurp.<hostname>  will  not  be
  60.               updated.
  61.  
  62.  
  63.  
  64. V1.08                     20 August 1993                        1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. SLURP(1)                                                 SLURP(1)
  71.  
  72.  
  73.        -l     Local time  is  used  to  set  the  start  time  in
  74.               slurp.<hostname>   for  the  next  news  retrieval,
  75.               rather than setting the start time through  a  call
  76.               to the tcp time service at the remote server.
  77.  
  78.        -r     A  'MODE  READER'  command  is  sent  to the remote
  79.               server. This is used when connecting  with  an  INN
  80.               site  which needs to be switched from innd to nnrpd
  81.               so the NEWNEWS command can be issued.
  82.  
  83.        -w     The time for the next news retrieval is not written
  84.               to slurp.<hostname>.
  85.  
  86.        hostname
  87.               The  hostname  of the remote NNTP server to connect
  88.               to. This must be specified.
  89.  
  90.        [/sublist]
  91.               If this is specified, then the entry  in  slurp.sys
  92.               which  contains /sublist after the hostname will be
  93.               used. This lets you take different groups from  the
  94.               same server at different times.
  95.  
  96.        [:timefile]
  97.               Use  this  to  specify an alternate filename to use
  98.               for the file  containing  the  time  for  the  next
  99.               NEWNEWS  at  a particular host. Normally slurp will
  100.               use the hostname, but this can  cause  problems  on
  101.               file systems with short filenames.
  102.  
  103.  
  104. CONFIGURATION FILES
  105.        There are two configuration files used by slurp.
  106.  
  107.    slurp.sys
  108.        Entries in slurp.sys take the form
  109.  
  110.               host-
  111.               name/sublist:groups/distributions:flags:username/password
  112.  
  113.        This  format should be familar to people who have used the
  114.        C News sys file. Entries for a particular host can be con-
  115.        tinued  on more than one line by using a '\' at the end of
  116.        the line. e.g.
  117.  
  118.               hostname:group1,group2,\
  119.               group3,group4,group5
  120.  
  121.        Slurp is even more picky about the presence of  whitespace
  122.        than  C  News.  It  can  only appear in comments. Comments
  123.        begin with a '#' and continue to the end of the line.
  124.  
  125.        Using distributions is  not  recommended  -  they're  only
  126.        really  included  for  completeness.  Under  current  NNTP
  127.  
  128.  
  129.  
  130. V1.08                     20 August 1993                        2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. SLURP(1)                                                 SLURP(1)
  137.  
  138.  
  139.        implementations, setting distributions requires the server
  140.        to open each article, search through for the distributions
  141.        line and check it against the supplied list. This will not
  142.        only  increase  the  load on the server substantially, but
  143.        increase the amount of time for the connection.
  144.  
  145.        There are 3 possible flags: i, l and r which have the same
  146.        meaning  as the command line options. If present, username
  147.        and password will be sent to the server  as  part  of  the
  148.        simple authorisation protocol when the connection is first
  149.        made.
  150.  
  151.    slurp.<hostname>[.<sublist>]
  152.        The file slurp.<hostname> contains  the  time  when  slurp
  153.        last connected to the NNTP server at <hostname>. If a sub-
  154.        list has been specified with the -s option then this  will
  155.        be appended with a period to the name.  slurp can then use
  156.        this time to pick up all the articles that have arrived at
  157.        the  server  since the last session. It may be followed on
  158.        subsequent lines by a list of message IDs of articles that
  159.        are to be retrieved from the server in the next session.
  160.  
  161.        Each  time  slurp is run and slurp.<hostname> updated, the
  162.        current slurp.<hostname> will be backed  up  in  the  file
  163.        slurp.<hostname>.o.
  164.  
  165.  
  166. OPERATION
  167.        When  run, slurp will first retrieve the appropriate news-
  168.        group list, distribution list and start time for the spec-
  169.        ified server, either from the configuration files or over-
  170.        riding those settings with the command line options.
  171.  
  172.        If the -w option is not set, then the current time will be
  173.        obtained to use as the start time for the next session. If
  174.        the -l option is specified, this will be  taken  from  the
  175.        local  machine,  otherwise  it  will be retrieved from the
  176.        remote server through a  call  to  the  tcp  time  service
  177.        there. If -i is not specified, then the message IDs of any
  178.        articles which were not retrieved in the last session will
  179.        be loaded from slurp.<hostname>.
  180.  
  181.        Slurp  will  now  connect to the NNTP server at the remote
  182.        host. If a username and password for use with  the  simple
  183.        authorisation  protocol  have been supplied then they will
  184.        be sent to the server. If the -r option is specified, then
  185.        a  'MODE  READER'  command  will be sent, to ensure at INN
  186.        sites that slurp is talking to nnrpd.
  187.  
  188.        A NEWNEWS request will now be issued, asking for  all  the
  189.        articles  that have arrived in the specified list of news-
  190.        groups since the specified time. The server  will  respond
  191.        with a list of message IDs. If a message ID is not already
  192.        present in the local history file, then it will be  stored
  193.  
  194.  
  195.  
  196. V1.08                     20 August 1993                        3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. SLURP(1)                                                 SLURP(1)
  203.  
  204.  
  205.        in  memory.  If the list of newsgroups is too large to fit
  206.        on one line (NNTP has a maximum line length of 512 charac-
  207.        ters)  then  a  series of NEWNEWS requests will be carried
  208.        out, adding further message IDs to the memory list if they
  209.        are not already present.
  210.  
  211.        Once  this has been completed, slurp moves into an article
  212.        retrieval stage. It will go through the  list  of  message
  213.        IDs  in  memory  and request them in turn from the server,
  214.        adding each article to the batch of articles being  either
  215.        stored  in  the incoming news directory or piped to rnews.
  216.        When a batch is found to be larger than the maximum  size,
  217.        it will be submitted to the news system.
  218.  
  219.        Once all the articles have been retrieved, the final batch
  220.        of articles will be submitted. If the -w  option  has  not
  221.        been set, then the previously obtained time to use for the
  222.        next NEWNEWS will be written to slurp.<hostname>.   If  an
  223.        error  has  occurred,  then  the  message IDs of any unre-
  224.        trieved articles  are  also  written  to  this  file,  for
  225.        retrieval in the next session.
  226.  
  227.        Statistics  on the connection will be logged to syslog (or
  228.        stderr if syslog is not available). The new article  count
  229.        is  the  total number of articles that have been submitted
  230.        to the new system. The duplicate count is how many message
  231.        IDs  were  found  to already exist on the local system. If
  232.        two NEWNEWS requests are necessary and a  message  ID  was
  233.        returned  by both requests, then it will be included twice
  234.        in the duplicate count. The missing count is  those  arti-
  235.        cles  which  were  in the server's history file but didn't
  236.        exist as actual article files, usually because  they  have
  237.        been  cancelled.  If  configured, the speed of transfer of
  238.        the article retrieval stage will also be logged.
  239.  
  240.  
  241. RETURN CODES
  242.        Slurp returns a series of return codes which may be useful
  243.        to controlling programs:-
  244.               0 - Successful completion
  245.               1 - General system error
  246.               2  - Incorrect arguments supplied or incorrect con-
  247.               figuration files.
  248.               3 - Error occurred during  attempt  to  connect  to
  249.               remote host
  250.               4 - NNTP Protocol error
  251.               5  -  Insufficient  disk  space  available for news
  252.               batch.
  253.  
  254.  
  255. FILES
  256.        /usr/lib/news/slurp.sys
  257.        /usr/lib/news/slurp.<hostname>
  258.  
  259.  
  260.  
  261.  
  262. V1.08                     20 August 1993                        4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. SLURP(1)                                                 SLURP(1)
  269.  
  270.  
  271. AUTHOR
  272.        Stephen Hebditch <steveh@orbital.demon.co.uk>
  273.  
  274. SEE ALSO
  275.        rnews(8)
  276.        RFC977 - Network News Transfer Protocol (NNTP),
  277.        RFC1036 - Usenet Article Format standard.
  278.  
  279.  
  280.  
  281.  
  282.  
  283.  
  284.  
  285.  
  286.  
  287.  
  288.  
  289.  
  290.  
  291.  
  292.  
  293.  
  294.  
  295.  
  296.  
  297.  
  298.  
  299.  
  300.  
  301.  
  302.  
  303.  
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.  
  311.  
  312.  
  313.  
  314.  
  315.  
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328. V1.08                     20 August 1993                        5
  329.  
  330.  
  331.