unixdev.net


Switch to SpeakEasy.net DSL

The Modular Manual Browser

Home Page
Manual: (OSF1-V5.1-alpha)
Page:
Section:
Apropos / Subsearch:
optional field



FORMAIL(1)							   FORMAIL(1)



NAME
  formail - mail (re)formatter

SYNOPSIS
  formail [+skip] [-total] [-vbczfrktedqBY] [-p	prefix]
       [-D maxlen idcache]
       [-x headerfield]	[-X headerfield]
       [-a headerfield]	[-A headerfield]
       [-i headerfield]	[-I headerfield]
       [-u headerfield]	[-U headerfield]
       [-R oldfield newfield]
       [-n [maxprocs ]]	[-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

  -v   Formail will print its version number and exit.

  -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	whitespace exists between field	name and content.  Zap fields
       which  contain  only  a	single whitespace character.  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  causes  formail  to  select  the  header  sender  instead of the
       envelope	sender for the reply.  This option should be used  when	 gen-
       erating	auto-reply  headers  from news articles	or when	the sender of
       the message is expecting	a reply.

  -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 [maxprocs]
       Tell formail not	to wait	for every program to finish  before  starting
       the  next  (causes  splits  to  be  processed  in parallel).  Maxprocs
       optionally specifies an upper limit on the number of concurrently run-
       ning processes.

  -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	headerfields  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
       envelope	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.

NOTES
  When renaming, removing, or extracting fields, partial  fieldnames  may  be
  used to specify all fields that start	with the specified value.

  By default, when generating  an  auto-reply  header  procmail	 selects  the
  envelope  sender from	the input message.  This is correct for	vacation mes-
  sages	and other automatic replies regarding the routing or delivery of  the
  original message.  If	the sender is expecting	a reply	or the reply is	being
  generated in response	to the contents	of the original	message	then  the  -t
  option should	be used.

  RFC822, the original standard	governing the format of	 Internet  mail	 mes-
  sages,  did not specify whether Resent header	fields (those that begin with
  `Resent-', such as `Resent-From:') should be considered when	generating  a
  reply.  Since	then, the recommended usage of the Resent headers has changed
  to consider them as purely informational and not for use when	normally gen-
  erating  a reply.  While formail now ignores Resent headers when generating
  header replies, versions of formail prior to 3.14 gave such headers a	 high
  precedence.	If the old behavior is needed for established applications it
  can be specified by  calling	formail	 with  the  option  `-a	 Resent-'  in
  addition to the -r and -t options.  This usage is deprecated and should not
  be used in new applications.





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	 dis-
       abled.

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'

  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),	RFC822,
  RFC1123

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 following 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
			 diagnostic 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 executable.

  File table full	 Too many open files on	this machine.

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

  No-wait option ignored to prevent corrupt idcache
			 The -n	and -D options cannot be safely	used  togeth-
			 er, so	the former was ignored.

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 incoming mail (which in turn depends on both the original
  sender's mail	agent and the mailinglist setup) formail could decide to gen-
  erate	an autoreply header that replies to the	list.

BUGS
  When formail has to generate a leading `From ' line it normally  will	 con-
  tain	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 regen-
  erate	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 un-
  til the program it receives the input	from terminates	itself.

  If formail is	instructed to generate an autoreply mail, it will  never  put
  more than one	address	in the `To:' field.

MISCELLANEOUS
  Formail is eight-bit clean.

  When formail has to determine	the sender's address, every RFC822 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.14) avail-
  able at http://www.procmail.org/ or ftp.procmail.org in pub/procmail/.

MAILINGLIST
  There	exists a mailinglist for questions relating to	any  program  in  the
  procmail package:
       <procmail-usersATprocmail.org>
	 for submitting	questions/answers.
       <procmail-users-requestATprocmail.org>
	 for subscription requests.

  If you would like to stay informed about new versions	and official  patches
  send a subscription request to
       procmail-announce-requestATprocmail.org
  (this	is a readonly list).

AUTHOR
  Stephen R. van den Berg
       <srbATcuci.nl>