Initial revision

svn path=/trunk/; revision=4

1 files changed, 398 insertions, 0 deletions

diff --git a/fetchmail.man b/fetchmail.man
new file mode 100644
index 00000000..03c3275f
--- /dev/null
+++ b/fetchmail.man
@@ -0,0 +1,398 @@
+\. /* Copyright 1993-95 by Carl Harris, Jr.
+\.  * All rights reserved
+\.  *
+\.  * Distribute freely, except: don't remove my name from the source or
+\.  * documentation (don't take credit for my work), mark your changes (don't
+\.  * get me blamed for your possible bugs), don't alter or remove this
+\.  * notice.  May be sold if buildable source is provided to buyer.  No
+\.  * warrantee of any kind, express or implied, is included with this
+\.  * software; use at your own risk, responsibility for damages (if any) to
+\.  * anyone resulting from the use of this software rests entirely with the
+\.  * user.
+\.  *
+\.  * Send bug reports, bug fixes, enhancements, requests, flames, etc., and
+\.  * I'll try to keep a version up to date.  I can be reached as follows:
+\.  * Carl Harris <ceharris@vt.edu>
+\.  */
+\.
+\. $Log: fetchmail.man,v $
+\. Revision 1.1  1996/06/24 19:30:36  esr
+\. Initial revision
+\.
+\. Revision 1.4  1995/09/07 22:53:49  ceharris
+\. One last bit of crap before the 3.0b4 release
+\.
+\. Revision 1.3  1995/08/14 18:36:46  ceharris
+\. Patches to support POP3's LAST command.
+\. Final revisions for beta3 release.
+\.
+\. Revision 1.2  1995/08/08 01:01:29  ceharris
+\. Added GNU-style long options processing.
+\. Fixed password in 'ps' output problem.
+\. Fixed various RCS tag blunders.
+\. Integrated .poprc parser, lexer, etc into Makefile processing.
+\.
+\.
+.TH popclient LOCAL
+.SH NAME
+popclient \- retrieve mail from a mailserver using Post Office Protocol.
+.SH SYNOPSIS
+.B popclient
+[\fI options \fR] \fI server-host [server-host...]\fR
+.SH DESCRIPTION
+.I popclient
+is a Post Office Protocol compliant mail retrieval client which supports 
+both POP2 (as specified in RFC 937) and POP3 (RFC 1725).
+.PP
+Typically,
+.I popclient
+will be used to download mail in batch from the remote mailserver specified by
+.I host
+to a mail folder on the local disk.  The retrieved mail will then be 
+manipulated using a local mail reader, such as
+.I mail
+or 
+.I elm.
+.PP
+To facilitate the use of
+.I popclient
+in scripts, pipelines, etc, it returns an appropriate exit code upon 
+termination -- see EXIT CODES below.
+.SH OPTIONS
+.TP
+.B \-2
+Use Post Office Protocol version 2 (POP2).  See also the 
+.B \--protocol
+option, below.
+.TP
+.B \-3
+Use Post Office Protocol version 3 (POP3).  See also the
+.B \--protocol
+option, below.
+.TP
+.B \-a, --all
+POP3 only.  Retrieve both old (previously retrieved) and new messages from 
+the mailserver.
+.TP
+.B \-c, --stdout
+Causes retrieved messages to be written to stdout instead of a mail folder.
+See OUTPUT OPTIONS below for a complete description.  You may not specify
+both the
+.B \-c
+and 
+.B \-o
+options on the same command line.
+.TP
+.B \-F, --flush
+POP3 only.  Delete old (previously retrieved) messages from the mailserver
+before retrieving new messages.
+.TP
+.B \-f pathname, --poprc pathname
+Specify an alternate name for the .poprc file.
+.TP
+.B \-k, --keep
+Keep retrieved messages in folder on remote mailserver.  Normally, messages 
+are deleted from the folder on the mailserver after they have been retrieved
+(unless 
+.I popclient
+was compiled with the KEEP_IS_DEFAULT option).  Specifying the 
+.B keep 
+option causes retrieved messages to remain in your folder on the mailserver.
+.TP
+.B \-K, --kill
+Delete retrieved messages from the remote mailserver.  If 
+.I popclient
+is compiled with the KEEP_IS_DEFAULT option, the
+.B kill
+option forces retrieved mail to be deleted.
+.TP
+.B \-l lines, --limit lines
+POP3 only.  Retrieve no more than the specified number of lines of each
+message body (plus message headers).  The
+.B keep
+option is implied by the
+.B limit
+option -- i.e. messages downloaded with the 
+.B limit
+option remain on the remote mailserver.
+.TP
+.B \-p string, --password string
+Specifies the password 
+.I string 
+to be used when logging-in to the mailserver.  The 
+appropriate password is both server and user dependent.  If the 
+.B password 
+option is not used to specify a password, you will be prompted 
+for a password before the connection to the mailserver is established.  
+See USER AUTHENTICATION below for a complete description.
+.TP
+.B \--protocol proto
+Specify the protocol to used when communicating with the remote 
+mailserver.  
+.I proto 
+may be one of the following:
+.RS
+.IP POP2 
+Post Office Protocol 2
+.IP POP3
+Post Office Protocol 3
+.IP APOP
+Use POP3 with MD5 authentication.
+.IP RPOP
+Use POP3 with trusted-host-based authentication (like rlogin/rsh). 
+.I popclient
+must be installed as a setuid root program to use RPOP.
+.B \--proto.
+.RE
+.TP
+.B \-o folder, --local folder
+Causes retrieved messages to be appended to file named by the folder 
+argument.  When neither 
+.B \-o
+nor
+.B \-c
+is specified, retrieved messages are appended to the system default mail 
+folder. See OUTPUT OPTIONS below for a complete description.
+.TP
+.B \-r folder, --remote folder
+Causes an alternate mail folder on the mailserver to be retrieved.  The
+syntax of the folder name is server dependent, as is the default behavior
+when no folder is specified.  Fortunately, most POP servers have a reasonable
+default behavior, so use of this option should be limited to fairly specialized
+applications.  POP3 does not provide a folder specification in the protocol.
+If the
+.B remote
+option is used in conjunction with the POP3 protocol, the remote folder 
+specification is ignored.
+.TP
+.B \-s, --silent
+Silent mode.  Suppresses all progress/status messages that are normally
+echoed to stderr during a POP connection.  If both the 
+.B silent
+and
+.B verbose
+options are specified, the 
+.B verbose
+option takes precedence.
+.TP
+.B \-u name, --username name
+Specifies the user idenfication to be used when logging-in to the mailserver.
+The appropriate user identification is both server and user dependent.  
+The default is your login name on the machine that is running 
+.I popclient.
+See USER AUTHENTICATION below for a complete description.
+.TP
+.B \-v, --verbose
+Verbose mode.  All control messages passed between 
+.I popclient
+and the mailserver are echoed to stderr.  Specifying
+.B verbose
+causes normal progress/status messages which would be redundant or meaningless
+to be modified or omitted.
+.TP
+.B \-V, --version
+Displays the version information for your copy of 
+.I popclient.
+If you specify the 
+.B \version
+option, all other options are ignored and no POP connection is made.
+.TP
+.PP
+.SH PROTOCOL SELECTION
+The selection of the correct Post Office Protocol (POP2 or POP3) depends upon
+the configuration of the mailserver from which you retrieve your mail.  The
+system adminstrator who installed 
+.I popclient
+on your system should have chosen an appropriate default protocol for your 
+mailserver.  If you get the message 'Connection refused' when using the 
+default protocol, try specifying
+.B \-2
+or
+.B \-3
+to select a different protocol.  If the 'Connection refused' message persists 
+regardless of the protocol selected, it is likely that your mailserver is not 
+running a POP compliant mail service.
+.PP
+.SH USER AUTHENTICATION
+User authentication in 
+.I popclient
+is very much like the authentication mechanism of 
+.I ftp(1).
+The correct user-id and password depend upon the underlying security
+system at the mailserver.  
+.PP
+If the mailserver is a Unix machine on which you have an ordinary user 
+account, your regular login name and password are used with 
+.I popclient.
+If you use the same login name on both the server and the client machines,
+you needn't worry about specifying a user-id with the 
+.B \-u
+option \-\- 
+the default behavior will use your login name on the client machine as the 
+user-id on the server machine.  If you use a different login name
+on the server machine, specify that login name with the
+.B \-u
+option.  e.g. if your login name is 'jsmith' on a machine named 'mailgrunt',
+you would start 
+.I popclient 
+as follows:
+.IP
+popclient -u jsmith mailgrunt
+.PP
+The default behavior of 
+.I popclient
+is to prompt you for your mailserver password before the POP connection is
+established.  This is the safest way to use 
+.I popclient
+and ensures that your password will not be compromised.  You may also specify
+your password using the  
+.B \-p
+option.  This is convenient when using 
+.I popclient
+with automated scripts, but it may result in your password being exposed to
+prying eyes \-\- be careful!  Regardless of how your password is specified
+it is never stored in shared memory segments, or left unencrypted in the core 
+image when
+.I popclient
+terminates.  Continuing the preceding example, suppose your password on
+\'mailgrunt' is 'Gr8PassWd'.  The syntax would be:
+.IP
+popclient -u jsmith -p Gr8PassWd mailgrunt
+.PP
+On mailservers that do not provide ordinary user accounts, your user-id and 
+password are usually assigned by the server administrator when you apply for 
+a mailbox on the server.  Contact your server administrator if you don't know 
+the correct user-id and password for your mailbox account.
+.PP
+.SH OUTPUT OPTIONS
+.I popclient
+always writes the retrieved messages using Unix mail folder format.  This
+allows 
+.I popclient
+to be used in conjunction with common mail readers like
+.I mail
+and
+.I elm.
+The retrieved messages are normally appended to your default system mailbox
+on the local disk, using the local Mail Delivery Agent (MDA), usually 
+/bin/mail(1), so that when you invoke your mail reader it can manipulate the 
+retrieved messages like any other mail you receive on the client machine.  
+.PP
+Using the 
+.B \-o
+option, you can specify a different mail folder to which the retrieved
+messages will be appended.  If you prefer, for example, to have your POP
+mail from a machine called 'mailgrunt' stored in the 
+.I mbox
+file in your home directory, you would start 
+.I popclient
+as follows:
+.IP 
+popclient \-o $HOME/mbox mailgrunt
+.PP
+Note that the folder specified with
+.B \-o
+is not locked or otherwise protected from other processes writing to it 
+while popclient is writing to it.  
+.PP
+.I popclient
+can be used in a shell pipeline by using the 
+.B \-c
+option.  In this mode, 
+.I popclient
+writes the retrieved messages to stdout, instead of a mail folder.  This would
+allow you, for instance, to pass the incoming mail through a filter that
+discards mail marked as 'Precedence: junk'.  Suppose you've written an AWK
+script called 'dumpjunk.awk' to implement a junk mail filter.  The appropriate
+syntax to retrieve your mail from 'mailgrunt', pass it through the filter,
+and write it to a folder called 'realmail' in your home directory would be:
+.IP
+popclient -c mailgrunt | awk -f dumpjunk.awk > $HOME/realmail
+.PP
+The progress/status messages written to stderr when the 
+.B \-s
+option has not been specified, do not interfere with the message stream, which 
+is written to stdout.  You may even use 
+.B \-v
+and 
+.B \-c
+together without corrupting the message stream.  It is a good idea to use the
+.B \-k
+option when using 
+.B \-c
+to insure that your messages will not be lost if part of the shell pipeline 
+does not function incorrectly.  The safest bet would be something like:
+.IP
+popclient -k -c mailgrunt | myfilter > $HOME/filtered.mail
+.PP
+followed by
+.IP
+popclient -c mailgrunt > /dev/null
+.PP
+when you're sure the messages were correctly processed by 'myfilter'.
+.PP
+.SH EXIT CODES
+To facilitate the use of 
+.I popclient
+in shell scripts and the like, an exit code is returned to give an indication
+of what occured during a given POP connection.  The exit code can be tested
+by the script and appropriate action taken.
+.PP
+A simple example follows.  This Bourne shell script executes 
+.I popclient
+and, if some messages were successfully retrieved from a mailserver retrieved
+from the command line, it starts the 
+.I mail
+utility to read those messages.  Otherwise, it prints a brief message, and
+exits.
+.EX 0
+#!/bin/sh
+
+if popclient $1
+then
+  mail
+else
+  echo "No mail to read."
+fi
+.EE
+.PP
+The exit codes returned by 
+.I popclient
+are as follows:
+.IP 0
+One or more messages were successfully retrieved.
+.IP 1
+There was no mail awaiting retrieval.
+.IP 2
+An error was encountered when attempting to open a socket for the POP 
+connection.  If you don't know what a socket is, don't worry about it --
+just treat this as an 'unrecoverable error'.
+.IP 3
+The user authentication step failed.  This usually means that a bad 
+user-id or password was specified.
+.IP 4
+Some sort of protocol error was detected.  POP is not especially forgiving
+when it comes to unexpected responses, commands, etc -- the protocol invariably
+calls for terminating the connection under such error conditions.
+.IP 5
+There was a syntax error in the arguments to 
+.I popclient.
+.IP 6
+Some kind of I/O woes occurred when writing to the local folder.
+.IP 7
+There was an error condition reported by the server (POP3 only).
+.IP 9
+Something totally undefined occured.  This is usually caused by a bug within
+.I popclient.
+Do let me know if this happens.
+.PP
+.SH AUTHOR
+.I popclient
+was written by Carl Harris at Virginia Polytechnic Institute and State   
+University (a.k.a. Virginia Tech).
+.PP
+.SH BUGS
+There are none!  Well, maybe one or two.  Send comments, bug reports, gripes, 
+and the like to ceharris@mal.com.
+.SH SEE ALSO
+mail(1), binmail(1), sendmail(8), popd(8), RFC 937, RFC 1225.