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.







            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  mes-
            sages,  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  pro-
            cessed 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.



            write  errors, duplicate messages and mismatched Con-
            tent-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 Mes-
            sage-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  spec-
            ify  either  one  of  the  field names Message-ID: or
            Resent-Message-ID: with no field contents, then  for-
            mail 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.






            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 preset-
            ting FILENO, you can change the initial message  num-
            ber  being used and the width of the zero-padded out-
            put.  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 <old_mailbox >>new_mailbox

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

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

       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 fol-
                              lowing 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 exe-
                              cutable.

       File table full        Too many open  files  on  this  ma-
                              chine.

       Invalid field-name: "x"
                              The  specified  field-name "x" con-
                              tains 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  in-
       coming  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.


       When formail has to generate a leading  `From  '  line  it
       normally  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 expected 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,
       include -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  re-
       ceives 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 (delet-
       ing excessive comments and whitespace).

       The regular expression that is used to find  `real'  post-
       marks 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 verba-
       tim  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

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