sys/man/6/rewrite

   1 .TH REWRITE 6
   2 .SH NAME
   3 rewrite \- mail rewrite rules
   4 .SH SYNOPSIS
   5 .B /mail/lib/rewrite
   6 .SH DESCRIPTION
   7 .IR Mail (1)
   8 uses rewrite rules to convert mail destinations into
   9 commands used to dispose of the mail.
  10 Each line of the file
  11 .F /mail/lib/rewrite
  12 is a rule.
  13 Blank lines and lines beginning with
  14 .B #
  15 are ignored.
  16 .PP
  17 Each rewriting rule consists of (up to) 4 strings:
  18 .TF pattern
  19 .TP
  20 .I pattern
  21 A regular expression in the style of
  22 .IR regexp (6).
  23 The
  24 .I pattern
  25 is applied to mail destination addresses.
  26 The pattern match is case-insensitive
  27 and must match the entire address.
  28 .TP
  29 .I type
  30 The type of rule; see below.
  31 .TP
  32 .I arg1
  33 An
  34 .IR ed (1)
  35 style replacement string, with
  36 .BI \e n
  37 standing for the text matched by the
  38 .IR n th
  39 parenthesized subpattern.
  40 .TP
  41 .I arg2
  42 Another
  43 .IR ed (1)
  44 style replacement string.
  45 .PD
  46 .PP
  47 In each of these fields the substring
  48 .B \es
  49 is replaced by the login id of the
  50 sender and the substring
  51 .B \el
  52 is replaced by the name of the local machine.
  53 .PP
  54 When delivering a message,
  55 .I mail
  56 starts with the first rule and continues down the list until a pattern
  57 matches the destination address.
  58 It then performs one of the following actions depending on the
  59 .I type
  60 of the rule:
  61 .TF alias
  62 .TP
  63 .B >>
  64 Append the mail to the file indicated by expanding
  65 .IR arg1 ,
  66 provided that file appears to be a valid mailbox.
  67 .TP
  68 .B |
  69 Pipe the mail through the command formed from concatenating the
  70 expanded
  71 .I arg1
  72 and
  73 .IR arg2 .
  74 .TP
  75 .B alias
  76 Replace the address by the address(es) specified
  77 by expanding
  78 .I arg1
  79 and recur.
  80 .TP
  81 .B translate
  82 Replace the address by the address(es) output by the
  83 command formed by expanding
  84 .I arg1
  85 and recur.
  86 .PD
  87 .PP
  88 .I Mail
  89 expands the addresses recursively until each address has matched a
  90 .B >>
  91 or
  92 .B |
  93 rule or until the recursion depth indicates a rewriting loop
  94 (currently 32).
  95 .PD
  96 .PP
  97 If
  98 .IR mail (1)
  99 is called with more than one address and
 100 several addresses match
 101 .B |
 102 rules and result in the same
 103 expanded
 104 .IR arg1 ,
 105 the message is delivered to all those addresses
 106 by a single command,
 107 composed by concatenating the common expanded
 108 .I arg1
 109 and each expanded
 110 .IR arg2 .
 111 This mail bundling is performed to reduce the number
 112 of times the same message is transmitted across a
 113 network.  For example, with the following
 114 rewrite rule
 115 .PP
 116 .EX
 117    ([^!]*\.bell-labs\.com)!(.*)  |  "/mail/lib/qmail '\es' 'net!\e1'" "'\e2'"
 118 .EE
 119 .PP
 120 if user
 121 .B presotto
 122 runs the command
 123 .PP
 124 .EX
 125    % mail plan9.bell-labs.com!ken plan9.bell-labs.com!rob
 126 .EE
 127 .PP
 128 there will follow only one execution of the command
 129 .PP
 130 .EX
 131    /mail/lib/qmail presotto net!plan9.bell-labs.com ken rob
 132 .EE
 133 .PP
 134 Here
 135 .B /mail/lib/qmail
 136 is an
 137 .IR rc (1)
 138 script used for locally queuing remote mail.
 139 .PP
 140 In the event of an error, the disposition of the mail depends on the name of the
 141 command executing the rewrite.  If the command is called
 142 .B mail
 143 and is run by
 144 .BR $user ,
 145 the command will print an error and deposit the message in
 146 .BR /mail/box/$user/dead.letter .
 147 If the command is called
 148 .BR rmail ,
 149 usually because it was invoked to deliver mail arriving over the network,
 150 the message will be returned to the sender.  The returned message will
 151 appear to have been sent by user
 152 .BR postmaster .
 153 .SH "SEE ALSO"
 154 .IR mail (1)