home *** CD-ROM | disk | FTP | other *** search
/ OS/2 Shareware BBS: 35 Internet / 35-Internet.zip / popc221h.zip / popclient.man < prev    next >
Text File  |  1994-09-16  |  13KB  |  331 lines
  1.  
  2.  
  3.  
  4. popclient(1L)                                       popclient(1L)
  5.  
  6.  
  7. NAME
  8.        popclient  -  retrieve  mail  from a mailserver using Post
  9.        Office Protocol.
  10.  
  11. SYNOPSIS
  12.        popclient  [-2  |  -3]  [-Vksv]  [-u  server-userid]   [-p
  13.        server-password]
  14.        [-f remote-folder] [-c | -o local-folder]  host
  15.  
  16. DESCRIPTION
  17.        popclient   is  a  Post  Office  Protocol  compliant  mail
  18.        retrieval client which supports both POP2 (as specified in
  19.        RFC 937) and POP3 (RFC 1225).
  20.  
  21.        Typically,  popclient  will  be  used  to download mail in
  22.        batch from the remote mailserver specified by  host  to  a
  23.        mail  folder  on  the local disk.  The retrieved mail will
  24.        then be manipulated using a local  mail  reader,  such  as
  25.        mail or elm.
  26.  
  27.        To  facilitate the use of popclient in scripts, pipelines,
  28.        etc, it returns an appropriate exit code upon  termination
  29.        -- see EXIT CODES below.
  30.  
  31. OPTIONS
  32.        -2     Use Post Office Protocol version 2 (POP2).
  33.  
  34.        -3     Use Post Office Protocol version 3 (POP3).
  35.  
  36.        -k     Keep messages in folder on remote mailserver.  Nor-
  37.               mally, messages are deleted from the folder on  the
  38.               mailserver  after they have been retrieved.  Speci-
  39.               fying -k causes retrieved  messages  to  remain  in
  40.               your folder on the mailserver.
  41.  
  42.        -s     Silent  mode.   Suppresses all progress/status mes-
  43.               sages that are normally echoed to stderr  during  a
  44.               POP  connection.  If both the -s and -v options are
  45.               specified, the -v option takes precedence.
  46.  
  47.        -v     Verbose mode.  All control messages passed  between
  48.               popclient  and the mailserver are echoed to stderr.
  49.               Specifying -v causes  normal  progress/status  mes-
  50.               sages which would be redundant or meaningless to be
  51.               modified or omitted.
  52.  
  53.        -u     Specifies the user idenfication  to  be  used  when
  54.               logging-in to the mailserver.  The appropriate user
  55.               identification is both server and  user  dependent.
  56.               Default  is  your login name on the machine that is
  57.               running popclient.  See USER  AUTHENTICATION  below
  58.               for a complete description.
  59.  
  60.        -p     Specifies  the  password to be used when logging-in
  61.  
  62.  
  63.  
  64.                                                                 1
  65.  
  66.  
  67.  
  68.  
  69.  
  70. popclient(1L)                                       popclient(1L)
  71.  
  72.  
  73.               to the mailserver.   The  appropriate  password  is
  74.               both  server  and user dependent.  If the -p option
  75.               is not used to specify  a  password,  you  will  be
  76.               prompted  for  a  password before the connection to
  77.               the mailserver is established.  See USER  AUTHENTI-
  78.               CATION below for a complete description.
  79.  
  80.        -f     Causes  an  alternate mail folder on the mailserver
  81.               to be retrieved.  The syntax of the folder name  is
  82.               server  dependent,  as is the default behavior when
  83.               no folder  is  specified.   Fortunately,  most  POP
  84.               servers  have a reasonable default behavior, so use
  85.               of this option should be limited to fairly special-
  86.               ized  applications.  POP3 does not provide a folder
  87.               specification in the protocol.  If the -f option is
  88.               used  in conjunction with the -3 option, the remote
  89.               folder specification is ignored.
  90.  
  91.        -o     Causes retrieved messages  to  be  appended  to  an
  92.               alternate mail folder on the local disk.  When nei-
  93.               ther -o nor -c is specified, retrieved messages are
  94.               appended  to  the  system  default mail folder. See
  95.               OUTPUT OPTIONS below for a complete description.
  96.  
  97.        -c     Causes retrieved messages to be written  to  stdout
  98.               instead of a mail folder.  See OUTPUT OPTIONS below
  99.               for a complete description.  You  may  not  specify
  100.               both  the  -c  and  -o  options on the same command
  101.               line.
  102.  
  103.        -V     Displays the version information for your  copy  of
  104.               popclient.  If you specify the -V option, all other
  105.               options are ignored and no POP connection is  made.
  106.  
  107.  
  108. PROTOCOL SELECTION
  109.        The selection of the correct Post Office Protocol (POP2 or
  110.        POP3) depends upon the  configuration  of  the  mailserver
  111.        from  which you retrieve your mail.  The system adminstra-
  112.        tor who installed popclient on  your  system  should  have
  113.        chosen   an   appropriate   default   protocol   for  your
  114.        mailserver.  If you get the message  'Connection  refused'
  115.        when  using  the default protocol, try specifying -2 or -3
  116.        to  select  a  different  protocol.   If  the  'Connection
  117.        refused'  message  persists  regardless  of  the  protocol
  118.        selected, it is likely that your mailserver is not running
  119.        a POP compliant mail service.
  120.  
  121.  
  122. USER AUTHENTICATION
  123.        User  authentication  in  popclient  is very much like the
  124.        authentication mechanism of ftp(1).  The  correct  user-id
  125.        and password depend upon the underlying security system at
  126.        the mailserver.
  127.  
  128.  
  129.  
  130.                                                                 2
  131.  
  132.  
  133.  
  134.  
  135.  
  136. popclient(1L)                                       popclient(1L)
  137.  
  138.  
  139.        If the mailserver is a Unix machine on which you  have  an
  140.        ordinary  user  account, your regular login name and pass-
  141.        word are used with popclient.  If you use the  same  login
  142.        name  on  both  the  server  and  the client machines, you
  143.        needn't worry about  specifying  a  user-id  with  the  -u
  144.        option -- the default behavior will use your login name on
  145.        the client machine as the user-id on the  server  machine.
  146.        If  you  use a different login name on the server machine,
  147.        specify that login name with the -u option.  e.g. if  your
  148.        login name is 'jsmith' on a machine named 'mailgrunt', you
  149.        would start popclient as follows:
  150.  
  151.               popclient -u jsmith mailgrunt
  152.  
  153.        The default behavior of popclient is  to  prompt  you  for
  154.        your  mailserver  password  before  the  POP connection is
  155.        established.  This is the safest way to use popclient  and
  156.        ensures  that  your password will not be compromised.  You
  157.        may also specify your password using the -p option.   This
  158.        is convenient when using popclient with automated scripts,
  159.        but it may result in your password being exposed to prying
  160.        eyes  --  be  careful!  Regardless of how your password is
  161.        specified it is never stored in shared memory segments, or
  162.        left  unencrypted  in the core image when popclient termi-
  163.        nates.  Continuing the  preceding  example,  suppose  your
  164.        password  on 'mailgrunt' is 'Gr8PassWd'.  The syntax would
  165.        be:
  166.  
  167.               popclient -u jsmith -p Gr8PassWd mailgrunt
  168.  
  169.        On mailservers that do not provide ordinary user accounts,
  170.        your  user-id  and  password  are  usually assigned by the
  171.        server administrator when you apply for a mailbox  on  the
  172.        server.   Contact  your  server administrator if you don't
  173.        know the correct user-id and  password  for  your  mailbox
  174.        account.
  175.  
  176.  
  177. OUTPUT OPTIONS
  178.        popclient  always writes the retrieved messages using Unix
  179.        mail folder format.  This allows popclient to be  used  in
  180.        conjunction  with  common  mail readers like mail and elm.
  181.        The retrieved  messages  are  normally  appended  to  your
  182.        default  system mailbox on the local disk, using the local
  183.        Mail Delivery Agent (MDA), usually /bin/mail(1),  so  that
  184.        when  you  invoke  your  mail reader it can manipulate the
  185.        retrieved messages like any other mail you receive on  the
  186.        client machine.
  187.  
  188.        Using  the  -o  option,  you  can specify a different mail
  189.        folder to which the retrieved messages will  be  appended.
  190.        If  you  prefer, for example, to have your POP mail from a
  191.        machine called 'mailgrunt' stored in the mbox file in your
  192.        home directory, you would start popclient as follows:
  193.  
  194.  
  195.  
  196.                                                                 3
  197.  
  198.  
  199.  
  200.  
  201.  
  202. popclient(1L)                                       popclient(1L)
  203.  
  204.  
  205.               popclient -o $HOME/mbox mailgrunt
  206.  
  207.        Note  that  the  folder specified with -o is not locked or
  208.        otherwise protected from other  processes  writing  to  it
  209.        while popclient is writing to it.
  210.  
  211.        popclient  can be used in a shell pipeline by using the -c
  212.        option.  In this mode, popclient writes the retrieved mes-
  213.        sages  to  stdout,  instead  of a mail folder.  This would
  214.        allow you, for instance, to pass the incoming mail through
  215.        a  filter that discards mail marked as 'Precedence: junk'.
  216.        Suppose you've written an AWK script called 'dumpjunk.awk'
  217.        to  implement  a junk mail filter.  The appropriate syntax
  218.        to retrieve your mail from 'mailgrunt',  pass  it  through
  219.        the  filter, and write it to a folder called 'realmail' in
  220.        your home directory would be:
  221.  
  222.               popclient -c mailgrunt  |  awk  -f  dumpjunk.awk  >
  223.               $HOME/realmail
  224.  
  225.        The progress/status messages written to stderr when the -s
  226.        option has not been specified, do not interfere  with  the
  227.        message  stream, which is written to stdout.  You may even
  228.        use -v and -c  together  without  corrupting  the  message
  229.        stream.  It is a good idea to use the -k option when using
  230.        -c to insure that your messages will not be lost  if  part
  231.        of  the shell pipeline does not function incorrectly.  The
  232.        safest bet would be something like:
  233.  
  234.               popclient   -k   -c   mailgrunt   |   myfilter    >
  235.               $HOME/filtered.mail
  236.  
  237.        followed by
  238.  
  239.               popclient -c mailgrunt > /dev/null
  240.  
  241.        when  you're sure the messages were correctly processed by
  242.        'myfilter'.
  243.  
  244.  
  245. EXIT CODES
  246.        To facilitate the use of popclient in  shell  scripts  and
  247.        the  like,  an exit code is returned to give an indication
  248.        of what occured during a given POP connection.   The  exit
  249.        code  can  be  tested by the script and appropriate action
  250.        taken.
  251.  
  252.        A simple example follows.  This Bourne shell  script  exe-
  253.        cutes  popclient  and,  if some messages were successfully
  254.        retrieved from a mailserver  retrieved  from  the  command
  255.        line,  it  starts the mail utility to read those messages.
  256.        Otherwise,  it  prints  a  brief   message,   and   exits.
  257.        #!/bin/sh
  258.  
  259.  
  260.  
  261.  
  262.                                                                 4
  263.  
  264.  
  265.  
  266.  
  267.  
  268. popclient(1L)                                       popclient(1L)
  269.  
  270.  
  271.        if popclient $1 then
  272.          mail else
  273.          echo "No mail to read."  fi
  274.  
  275.        The exit codes returned by popclient are as follows:
  276.  
  277.        0      One or more messages were successfully retrieved.
  278.  
  279.        1      There was no mail awaiting retrieval.
  280.  
  281.        2      An  error was encountered when attempting to open a
  282.               socket for the POP connection.  If you  don't  know
  283.               what  a  socket  is,  don't  worry about it -- just
  284.               treat this as an 'unrecoverable error'.
  285.  
  286.        3      The user authentication step failed.  This  usually
  287.               means that a bad user-id or password was specified.
  288.  
  289.        4      Some sort of protocol error was detected.   POP  is
  290.               not  especially  forgiving  when  it comes to unex-
  291.               pected responses, commands,  etc  --  the  protocol
  292.               invariably  calls  for  terminating  the connection
  293.               under such error conditions.
  294.  
  295.        5      There was a syntax error in the arguments  to  pop-
  296.               client.
  297.  
  298.        6      Some  kind of I/O woes occurred when writing to the
  299.               local folder.
  300.  
  301.        7      There was an error condition reported by the server
  302.               (POP3 only).
  303.  
  304.        9      Something  totally undefined occured.  This is usu-
  305.               ally caused by a bug within popclient.  Do  let  me
  306.               know if this happens.
  307.  
  308.  
  309. AUTHOR
  310.        popclient was written by Carl Harris at Virginia Polytech-
  311.        nic Institute and State University (a.k.a. Virginia Tech).
  312.  
  313.  
  314. BUGS
  315.        There  are  none!  Well, maybe one or two.  Send comments,
  316.        bug reports, gripes, and the like to ceharris@vt.edu.
  317.  
  318. SEE ALSO
  319.        mail(1), binmail(1), sendmail(8), popd(8),  RFC  937,  RFC
  320.        1225.
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.                                                                 5
  329.  
  330.  
  331.