NAME
          formail - mail (re)formatter

     SYNOPSIS
          formail [+skip] [-total] [-bczfrktnedqBY] [-p prefix]
               [-D maxlen idcache]
               [-x headerfield] [-X headerfield]
               [-a headerfield] [-A headerfield]
               [-i headerfield] [-I headerfield]
               [-u headerfield] [-U headerfield]
               [-R oldfield newfield]
               [-m minfields] [-s [command [arg ...]]]

     DESCRIPTION
          formail is a filter that can be  used  to  force  mail  into
          mailbox  format,  perform  `From  ' escaping, generate auto-
          replying headers, do  simple  header  munging/extracting  or
          split    up    a    mailbox/digest/articles    file.     The
          mail/mailbox/article contents will be expected on stdin.

          If formail is supposed to determine the sender of the  mail,
          but is unable to find any, it will substitute `foo@bar'.

          If formail is started without any command line  options,  it
          will  force  any  mail coming from stdin into mailbox format
          and will escape all bogus `From ' lines with a `>'.

     OPTIONS
          -b   Don't escape any  bogus  mailbox  headers  (i.e.  lines
               starting with `From ').

          -p prefix
               Define a different quotation prefix.  If unspecified it
               defaults to `>'.

          -Y   Assume traditional Berkeley  mailbox  format,  ignoring
               any Content-Length: fields.

          -c   Concatenate continued fields in the header.   Might  be
               convenient when postprocessing mail with standard (line
               oriented) text utilities.

          -z   Ensure a space exists between field name  and  content.
               Zap fields which contain only a space.  Zap leading and
               trailing whitespace on fields extracted with -x.

          -f   Force formail to  simply  pass  along  any  non-mailbox
               format (i.e. don't generate a `From ' line as the first
               line).

          -r   Generate an  auto-reply  header.   This  will  normally
               throw  away all the existing fields (except X-Loop:) in
               the original message, fields you wish to preserve  need
               to  be  named  using  the  -i  option.  If you use this
               option in conjunction with -k, you can prevent the body
               from being `escaped' by also specifying -b.

          -k   When  generating  the   auto-reply   header   or   when
               extracting fields, keep the body as well.

          -t   Trust the sender to have used a valid return address in
               his  header.   This  option  will  be  most useful when
               generating auto-reply headers from news  articles.   If
               this  option  is not turned on, formail tends to favour
               machine-generated addresses in the header.

          -s   The input will be split up into separate mail messages,
               and  piped  into a program one by one (a new program is
               started for every part).  -s has to be the last  option
               specified,  the first argument following it is expected
               to be the name of a program, any other  arguments  will
               be  passed  along to it.  If you omit the program, then
               formail will simply concatenate the splitted  mails  on
               stdout again.  See FILENO.

          -n   Tell formail not to wait for every  program  to  finish
               before starting the next (causes splits to be processed
               in parallel).

          -e   Do not require empty lines to be preceding  the  header
               of  a  new  message  (i.e.  the messages could start on
               every line).

          -d   Tell formail that the messages it is supposed to  split
               need  not  be in strict mailbox format (i.e. allows you
               to  split  digests/articles  or  non-standard   mailbox
               formats).   This  disables  recognition of the Content-
               Length: field.

          -B   Makes formail assume that it is splitting  up  a  BABYL
               rmail file.

          -m minfields
               Allows you to specify the number of consecutive  fields
               formail  needs  to  find before it decides it found the
               start of a new message, it defaults to 2.

          -q   Tells formail to (still  detect  but)  be  quiet  about
               write   errors,   duplicate   messages  and  mismatched
               Content-Length: fields.  This option is on by  default,
               to make it display the messages use -q-.

          -D maxlen idcache
               Formail will detect if the Message-ID  of  the  current
               message  has already been seen using an idcache file of
               approximately maxlen size.  If not splitting,  it  will
               return  success  if  a  duplicate  has  been found.  If
               splitting, it will not output duplicate  messages.   If
               used  in  conjunction with -r, formail will look at the
               mail address of the sender instead at the Message-ID.

          -x headerfield
               Extract the  contents  of  this  headerfield  from  the
               header, display it as a single line.

          -X headerfield
               Same as -x, but also preserves the field name.

          -a headerfield
               Append a custom headerfield onto the header;  but  only
               if  a similar field does not exist yet.  If you specify
               either one of the field names  Message-ID:  or  Resent-
               Message-ID:  with  no field contents, then formail will
               generate a unique message-ID for you.

          -A headerfield
               Append a custom headerfield  onto  the  header  in  any
               case.

          -i headerfield
               Same as -A, except that any existing similar fields are
               renamed   by   prepending   an   ``Old-''  prefix.   If
               headerfield consists only of a field-name, it will  not
               be appended.

          -I headerfield
               Same as -i, except that any existing similar fields are
               simply  removed.   If  headerfield  consists  only of a
               field-name, it effectively deletes the field.

          -u headerfield
               Make the first occurrence of  this  field  unique,  and
               thus delete all subsequent occurrences of it.

          -U headerfield
               Make the last occurrence of this field unique, and thus
               delete all preceding occurrences of it.

          -R oldfield newfield
               Renames all occurrences of the fieldname oldfield  into
               newfield.

          +skip
               Skip the first skip messages while splitting.

          -total
               Output at most total messages while splitting.

     ENVIRONMENT
          FILENO
               While splitting, formail  assigns  the  message  number
               currently being output to this variable.  By presetting
               FILENO, you can change the initial message number being
               used  and  the  width  of  the  zero-padded output.  If
               FILENO is unset it will default to 000.  If  FILENO  is
               non-empty   and  does  not  contain  a  number,  FILENO
               generation is disabled.

     EXAMPLES
          To split up a digest one usually uses:
               formail +1 -ds >>the_mailbox_of_your_choice
          or
               formail +1 -ds procmail

          To remove all Received: fields from the header:
               formail -I Received:

          To remove all fields except  From:  and  Subject:  from  the
          header:
               formail -k -X From: -X Subject:

          To supersede the Reply-To: field in a header you could use:
               formail -i "Reply-To: foo@bar"

          To convert a  non-standard  mailbox  file  into  a  standard
          mailbox file you can use:
               formail -ds >new_mailbox

          Or, if you have a very tolerant mailer:
               formail -a Date: -ds >new_mailbox

          To extract the header from a message:
               formail -X ""
          or
               sed -e '/^$/ q'

          To extract the body from a message:
               formail -I ""
          or
               sed -e '1,/^$/ d'

     SEE ALSO
          mail(1), binmail(1), sendmail(8), procmail(1), sed(1), sh(1)

     DIAGNOSTICS
          Can't fork             Too many processes on this machine.

          Content-Length: field exceeds actual length by nnn bytes
                                 The  Content-Length:  field  in   the
                                 header  specified  a  length that was
                                 longer than the  actual  body.   This
                                 causes   this  message  to  absorb  a
                                 number of subsequent messages follow-
                                 ing it in the same mailbox.

          Couldn't write to stdout
                                 The program that formail  was  trying
                                 to  pipe  into  didn't accept all the
                                 data formail sent to it;  this  diag-
                                 nostic  can  be  suppressed by the -q
                                 option.

          Duplicate key found: x The Message-ID or sender  x  in  this
                                 message  was  found  in  the idcache;
                                 this diagnostic can be suppressed  by
                                 the -q option.

          Failed to execute "x"  Program not in path, or  not  execut-
                                 able.

          File table full        Too many open files on this machine.

          Invalid field-name: "x"
                                 The specified field-name "x" contains
                                 control  characters,  or  cannot be a
                                 partial field-name for this option.

     WARNINGS
          You can save yourself and others a lot of grief if  you  try
          to  avoid  using  this  autoreply  feature  on  mails coming
          through mailinglists.  Depending on the format of the incom-
          ing  mail  (which  in  turn  depends  on  both  the original
          sender's mail agent and the mailinglist setup) formail could
          decide  to  generate an autoreply header that replies to the
          list.

     BUGS
          When formail has to generate a leading `From ' line it  nor-
          mally  will  contain  the current date.  If formail is given
          the option `-a Date:', it will use the date from the `Date:'
          field  in  the  header (if present).  However, since formail
          copies it verbatim, the format will differ from that expect-
          ed by most mail readers.

          If formail is instructed to delete  or  rename  the  leading
          `From  '  line,  it  will not automatically regenerate it as
          usual.  To force formail to regenerate it in this case,  in-
          clude -a 'From '.

          If formail is not called as the first program in a pipe  and
          it  is  told to split up the input in several messages, then
          formail will not terminate until the program it receives the
          input from terminates itself.

     MISCELLANEOUS
          Formail is eight-bit clean.

          When formail has to determine the  sender's  address,  every
          RFC  822  conforming  mail address is allowed.  Formail will
          always strip down the address to its minimal form  (deleting
          excessive comments and whitespace).

          The regular expression that is used to find `real' postmarks
          is:
               "\n\nFrom [\t ]*[^\t\n ]+[\t ]+[^\n\t ]"

          If a Content-Length: field is found  in  a  header,  formail
          will copy the number of specified bytes in the body verbatim
          before resuming the regular scanning for message  boundaries
          (except when splitting digests or Berkeley mailbox format is
          assumed).

     NOTES
          Calling up formail with the -h or -? options will  cause  it
          to display a command-line help page.

     SOURCE
          This program is part of the procmail mail-processing-package
          (v3.10   1994/10/31)   available   at  your  nearest  USENET
          comp.sources.misc  archive,   or   at   ftp.informatik.rwth-
          aachen.de as pub/packages/procmail/procmail.tar.gz.

     MAILINGLIST
          There exists a mailinglist for  questions  relating  to  any
          program in the procmail package:
               procmail@informatik.rwth-aachen.de
                    for submitting questions/answers.
               procmail-request@informatik.rwth-aachen.de
                    for subscription requests.

     AUTHOR
          Stephen R. van den Berg at RWTH-Aachen, Germany
               berg@pool.informatik.rwth-aachen.de