git.marmaro.de Git - mmh/blob - docs/historical/mh-6.8.5/conf/doc/RCS/mhook.rf,v

   1 head    1.16;
   2 access;
   3 symbols;
   4 locks; strict;
   5
   6
   7 1.16
   8 date    95.12.06.23.31.56;      author jromine; state Exp;
   9 branches;
  10 next    1.15;
  11
  12 1.15
  13 date    92.10.29.22.03.44;      author jromine; state Exp;
  14 branches;
  15 next    1.14;
  16
  17 1.14
  18 date    92.10.28.16.53.03;      author jromine; state Exp;
  19 branches;
  20 next    1.13;
  21
  22 1.13
  23 date    92.05.12.22.23.34;      author jromine; state Exp;
  24 branches;
  25 next    1.12;
  26
  27 1.12
  28 date    92.02.15.00.10.42;      author jromine; state Exp;
  29 branches;
  30 next    1.11;
  31
  32 1.11
  33 date    92.02.12.19.08.15;      author jromine; state Exp;
  34 branches;
  35 next    1.10;
  36
  37 1.10
  38 date    92.02.10.20.00.15;      author jromine; state Exp;
  39 branches;
  40 next    1.9;
  41
  42 1.9
  43 date    92.02.03.18.11.52;      author jromine; state Exp;
  44 branches;
  45 next    1.8;
  46
  47 1.8
  48 date    90.04.05.22.18.43;      author sources; state Exp;
  49 branches;
  50 next    1.7;
  51
  52 1.7
  53 date    90.04.05.22.12.11;      author sources; state Exp;
  54 branches;
  55 next    1.6;
  56
  57 1.6
  58 date    90.04.05.15.13.25;      author sources; state Exp;
  59 branches;
  60 next    1.5;
  61
  62 1.5
  63 date    90.03.22.11.31.26;      author sources; state Exp;
  64 branches;
  65 next    1.4;
  66
  67 1.4
  68 date    90.03.21.16.28.55;      author sources; state Exp;
  69 branches;
  70 next    1.3;
  71
  72 1.3
  73 date    90.03.20.19.42.05;      author sources; state Exp;
  74 branches;
  75 next    1.2;
  76
  77 1.2
  78 date    90.03.20.17.36.21;      author sources; state Exp;
  79 branches;
  80 next    1.1;
  81
  82 1.1
  83 date    90.03.20.17.21.04;      author sources; state Exp;
  84 branches;
  85 next    ;
  86
  87
  88 desc
  89 @@
  90
  91
  92 1.16
  93 log
  94 @document %{addresses} for rcvdist
  95 @
  96 text
  97 @.\"    @@(MHWARNING)
  98 .\" @@(#)$Id: mhook.rf,v 1.15 1992/10/29 22:03:44 jromine Exp jromine $
  99 .SC MHOOK 1
 100 .NA
 101 mhook, rcvdist, rcvpack, rcvtty  \- MH receive-mail hooks
 102 .SY
 103 .na
 104 .ti .5i
 105 @@(MHETCPATH)/rcvdist
 106 \%[\-form\ formfile]
 107 \%[switches\ for\ \fIpostproc\fR]
 108 address\ ...
 109 \%[\-help]
 110
 111 .ti .5i
 112 @@(MHETCPATH)/rcvpack
 113 file
 114 \%[\-help]
 115
 116 .ti .5i
 117 @@(MHETCPATH)/rcvtty
 118 \%[command]
 119 \%[\-form\ formatfile]
 120 \%[\-format\ string]
 121 \%[\-bell] \%[\-nobell]
 122 \%[\-newline] \%[\-nonewline]
 123 \%[\-biff]
 124 \%[\-help]
 125 .ad
 126 .DE
 127 A receive\-mail hook is a program that is run whenever you receive a
 128 mail message.
 129 You do \fBNOT\fR invoke the hook yourself,
 130 rather the hook is invoked on your behalf by your
 131 system's Message Transport Agent.  See \fIslocal\fP\0(1)
 132 for details on how to activate receive\-mail hooks on your system.
 133
 134 Four programs are currently available as part of \fIMH\fP,
 135 \fIrcvdist\fR (redistribute incoming messages to additional recipients),
 136 \fIrcvpack\fR (save incoming messages in a \fIpackf\fR'd file),
 137 and \fIrcvtty\fR (notify user of incoming messages).
 138 The fourth program,
 139 \fIrcvstore\fR\0(1) is described separately.
 140 They all reside in the \fI@@(MHETCPATH)/\fR directory.
 141
 142 The \fIrcvdist\fR program will resend a copy of the message to all of the
 143 addresses listed on its command line.
 144 It uses the format string facility described in \fImh\-format\fR\0(5).
 145 In addition, \fIrcvdist\fP
 146 also recognizes the following additional \fIcomponent\fR escape:
 147 .sp 1
 148 .ne 5
 149 .nf
 150 .ta \w'Dtimenow  'u +\w'Returns  'u
 151 \fIEscape\fR    \fIReturns\fR   \fIDescription\fR
 152 addresses       string  the addresses to distribute to
 153 .re
 154 .fi
 155
 156 The \fIrcvpack\fR program will append a copy of the message to the file listed
 157 on its command line.
 158 Its use is obsoleted by the \*(lqfile\*(rq action of \fIslocal\fR.
 159
 160 The \fIrcvtty\fR program executes the named file with the message as its
 161 standard input,
 162 and writes the resulting output
 163 on your terminal.
 164
 165 If no file is specified, or is bogus, etc.,
 166 then \fIrcvtty\fR will instead write a one\-line scan listing.
 167 Either the `\-form\ formatfile' or `\-format\ string' option may be used
 168 to override the default output format (see \fImh\-format\fP\0(5)).
 169 A newline is output before the
 170 message output, and the terminal bell is rung
 171 after the output.  The `\-nonewline' and `\-nobell' options
 172 will inhibit these functions.
 173
 174 In addition to the standard \fImh\-format\fR\0(5) escapes,
 175 \fIrcvtty\fR also recognizes the following additional \fIcomponent\fR escapes:
 176 .sp 1
 177 .ne 5
 178 .nf
 179 .ta \w'Dtimenow  'u +\w'Returns  'u
 180 \fIEscape\fR    \fIReturns\fR   \fIDescription\fR
 181 body    string  the (compressed) first part of the body
 182 dtimenow        date    the current date
 183 folder  string  the name of the current folder
 184 .re
 185 .fi
 186
 187 Normally, \fIrcvtty\fP obeys
 188 write permission as granted by \fImesg\fP\0(1).
 189 With the `\-biff' option, \fIrcvtty\fP will obey the notification
 190 status set by \fIbiff\fP\0(1) instead.
 191 If the terminal access daemon (TTYD) is available on your system,
 192 then \fIrcvtty\fR will give its output to the daemon for output
 193 instead of writing on the user's terminal.
 194 .Fi
 195 ^@@(MHETCPATH)/mtstailor~^tailor file
 196 ^$HOME/\&.maildelivery~^The file controlling local delivery
 197 ^@@(MHETCPATH)/maildelivery~^Rather than the standard file
 198 .Sa
 199 rcvstore (1), mh\-format(5), slocal(1)
 200 .Bu
 201 Only two return codes are meaningful, others should be.
 202 .En
 203 @
 204
 205
 206 1.15
 207 log
 208 @document additional rcvtty escapes
 209 @
 210 text
 211 @d2 1
 212 a2 1
 213 .\" @@(#)$Id: mhook.rf,v 1.14 1992/10/28 16:53:03 jromine Exp jromine $
 214 d49 10
 215 @
 216
 217
 218 1.14
 219 log
 220 @move slocal to (1)
 221 @
 222 text
 223 @d2 1
 224 a2 1
 225 .\" @@(#)$Id: mhook.rf,v 1.13 1992/05/12 22:23:34 jromine Exp jromine $
 226 d67 13
 227 @
 228
 229
 230 1.13
 231 log
 232 @fixup for nroff problems
 233 @
 234 text
 235 @d2 1
 236 a2 1
 237 .\" @@(#)$Id: mhook.rf,v 1.12 1992/02/15 00:10:42 jromine Exp jromine $
 238 d35 1
 239 a35 1
 240 system's Message Transport Agent.  See \fIslocal\fP\0(8)
 241 d80 1
 242 a80 1
 243 rcvstore (1), mh\-format(5), slocal (8)
 244 @
 245
 246
 247 1.12
 248 log
 249 @fix
 250 @
 251 text
 252 @d2 1
 253 a2 1
 254 .\" @@(#)$Id: mhook.rf,v 1.11 1992/02/12 19:08:15 jromine Exp jromine $
 255 d5 1
 256 a5 1
 257 mhook, rcvdist, rcvpack, rcvtty  \- MH receive\-mail hooks
 258 @
 259
 260
 261 1.11
 262 log
 263 @major revision
 264 @
 265 text
 266 @d2 1
 267 a2 1
 268 .\" @@(#)$Id: mhook.rf,v 1.10 1992/02/10 20:00:15 jromine Exp jromine $
 269 d71 1
 270 a71 1
 271 status set by \fIbiff\fP\0(1).
 272 @
 273
 274
 275 1.10
 276 log
 277 @replace $USER with "username"
 278 @
 279 text
 280 @d2 1
 281 a2 1
 282 .\" @@(#)$Id: mhook.rf,v 1.9 1992/02/03 18:11:52 jromine Exp jromine $
 283 d5 1
 284 a5 1
 285 mhook \- MH receive\-mail hooks
 286 d7 1
 287 a7 18
 288 $HOME/\&.maildelivery
 289 @@BEGIN: MHMTS
 290 .ds SL \fIpost\fR
 291 .ds ZS slocal
 292 @@END: MHMTS
 293 @@BEGIN: MMDFIMTS
 294 .ds SL \fIslocal\fR
 295 .ds ZS slocal
 296 @@END: MMDFIMTS
 297 @@BEGIN: MMDFIIMTS
 298 .ds SL the local channel
 299 .ds ZS mmdfII
 300 @@END: MMDFIIMTS
 301 @@BEGIN: SENDMTS
 302 .ds SL \fIslocal\fR
 303 .ds ZS slocal
 304 @@END: SENDMTS
 305
 306 d29 1
 307 d34 3
 308 a36 21
 309 @@BEGIN: MHMTS
 310 rather the hook is invoked on your behalf by \fIMH\fR.
 311 @@END: MHMTS
 312 @@BEGIN: MMDFIMTS
 313 rather the hook is invoked on your behalf by \fIMMDF\fR
 314 when you (symbolically) link @@(MHETCPATH)/slocal to the file
 315 bin/rcvmail in your home directory.
 316 @@END: MMDFIMTS
 317 @@BEGIN: MMDFIIMTS
 318 rather the hook is invoked on your behalf by \fIMMDF\fR.
 319 @@END: MMDFIIMTS
 320 @@BEGIN: SENDMTS
 321 rather the hook is invoked on your behalf by \fISendMail\fR,
 322 when you include the line
 323 .nf
 324 .in +.5i
 325     \*(lq| @@(MHETCPATH)/slocal -user username\*(rq
 326 .in -.5i
 327 .fi
 328 in your \&.forward file in your home directory.
 329 @@END: SENDMTS
 330 d38 1
 331 a38 223
 332 The \fI\&.maildelivery\fR file,
 333 which is an ordinary ASCII file,
 334 controls how local delivery is performed.
 335 This file is read by \*(SL.
 336 .if '\*(ZS'slocal' \{\
 337
 338 The format of each line in the \fI\&.maildelivery\fR file is
 339
 340 .ti +.5i
 341 \fBfield pattern action result string\fR
 342
 343 where
 344
 345 .in +.5i
 346 .ti -.25i
 347 \fBfield\fR:
 348 .br
 349 The name of a field that is to be searched for a pattern.
 350 This is any field in the headers of the message that might be present.
 351 In addition, the following special fields are also defined:
 352 .in +.25i
 353 \fIsource\fR: the out\-of\-band sender information
 354 .br
 355 \fIaddr\fR: the address that was used to cause delivery to the recipient
 356 .br
 357 \fIdefault\fR: this matches \fIonly\fR if the message hasn't been delivered yet
 358 .br
 359 \fI*\fR: this always matches
 360 .in -.25i
 361
 362 .ti -.25i
 363 \fBpattern\fR:
 364 .br
 365 The sequence of characters to match in the specified field.
 366 Matching is case\-insensitive but not RE\-based.
 367
 368 .ti -.25i
 369 \fBaction\fR:
 370 .br
 371 The action to take to deliver the message.
 372 This is one of
 373
 374 .in +.5i
 375 .ti -.5i
 376 \fIfile\fR or \fI>\fR:
 377 .br
 378 Append the message to the file named by \fBstring\fR.
 379 The message is appended to the file in the maildrop
 380 format which is used by your message transport system.
 381 If the message can be appended to the file,
 382 then this action succeeds.
 383
 384 When writing to the file,
 385 a new field is added:
 386
 387 .ti +.5i
 388 Delivery\-Date:\ date
 389
 390 which indicates the date and time that message was appended to the file.
 391
 392 .ti -.5i
 393 \fImbox\fR:
 394 .br
 395 Identical to \fIfile\fR,
 396 but always appends the message using the format used by \fIpackf\fR
 397 (the MMDF mailbox format).
 398
 399 .ti -.5i
 400 \fIpipe\fR or \fI|\fR:
 401 .br
 402 Pipe the message as the standard input to the command named by \fBstring\fR,
 403 using the Bourne shell \fIsh\fR\0(1) to interpret the string.
 404 Prior to giving the string to the shell,
 405 it is expanded with the following built\-in variables:
 406 .in +.25i
 407 $(sender): the return address for the message
 408 .br
 409 $(address): the address that was used to cause delivery to the recipient
 410 .br
 411 $(size): the size of the message in bytes
 412 .br
 413 $(reply\-to): either the \*(lqReply\-To:\*(rq or \*(lqFrom:\*(rq field
 414 of the message
 415 .br
 416 $(info): miscellaneous out\-of\-band information
 417 .in -.25i
 418
 419 When a process is invoked, its environment is:
 420 the user/group id:s are set to recipient's id:s;
 421 the working directory is the recipient's directory;
 422 the umask is 0077;
 423 the process has no /dev/tty;
 424 the standard input is set to the message;
 425 the standard output and diagnostic output are set to /dev/null;
 426 all other file\-descriptors are closed;
 427 the envariables \fB$USER\fR, \fB$HOME\fR, \fB$SHELL\fR are set
 428 appropriately,
 429 and no other envariables exist.
 430
 431 The process is given a certain amount of time to execute.
 432 If the process does not exit within this limit,
 433 the process will be terminated with extreme prejudice.
 434 The amount of time is calculated as ((size x 60) + 300) seconds,
 435 where size is the number of bytes in the message.
 436
 437 The exit status of the process is consulted in determining the success of the
 438 action.
 439 An exit status of zero means that the action succeeded.
 440 Any other exit status (or abnormal termination) means that the action failed.
 441
 442 In order to avoid any time limitations,
 443 you might implement a process that began by \fIforking\fR.
 444 The parent would return the appropriate value immediately,
 445 and the child could continue on,
 446 doing whatever it wanted for as long as it wanted.
 447 This approach is somewhat risky if the parent is going to return an
 448 exit status of zero.
 449 If the parent is going to return a non\-zero exit status,
 450 then this approach can lead to quicker delivery into your maildrop.
 451
 452 .ti -.5i
 453 \fIqpipe\fR or \fI<caret>\fR:
 454 .br
 455 Similar to \fIpipe\fR,
 456 but executes the command directly,
 457 after built\-in variable expansion,
 458 without assistance from the shell.
 459
 460 .ti -.5i
 461 \fIdestroy\fR:
 462 .br
 463 This action always succeeds.
 464 .in -.5i
 465
 466 .ti -.25i
 467 \fBresult\fR:
 468 .br
 469 Indicates how the action should be performed:
 470
 471 .in +.5i
 472 .ti -.5i
 473 \fIA\fR:
 474 .br
 475 Perform the action.
 476 If the action succeeds, then the message is considered delivered.
 477
 478 .ti -.5i
 479 \fIR\fR:
 480 .br
 481 Perform the action.
 482 Regardless of the outcome of the action,
 483 the message is not considered delivered.
 484
 485 .ti -.5i
 486 \fI?\fR:
 487 .br
 488 Perform the action only if the message has not been delivered.
 489 If the action succeeds, then the message is considered delivered.
 490
 491 .ti -.5i
 492 \fIN\fR:
 493 .br
 494 Perform the action only if the message has not been delivered
 495 and the previous action succeeded.
 496 If this action succeeds, then the message is considered delivered.
 497 .in -.5i
 498 .in -.5i
 499
 500 The file is always read completely,
 501 so that several matches can be made and several actions can be taken.
 502 The \fI\&.maildelivery\fR file must be owned either by the user or by root,
 503 and must be writable only by the owner.
 504 If the \fI\&.maildelivery\fR file can not be found,
 505 or does not perform an action which delivers the message,
 506 then the file @@(MHETCPATH)/maildelivery is read according to the same rules.
 507 This file must be owned by the root and must be writable only by the root.
 508 If this file can not be found
 509 or does not perform an action which delivers the message,
 510 then standard delivery to the user's maildrop, @@(MHDROPLOC), is performed.
 511
 512 Arguments in the \fI\&.maildelivery\fR file are separated by white\-space or
 513 comma.
 514 Since double\-quotes are honored,
 515 these characters may be included in a single argument by enclosing the
 516 entire argument in double\-quotes.
 517 A double\-quote can be included by preceeding it with a backslash.
 518
 519 To summarize, here's an example:
 520
 521 .nf
 522 .in +.5i
 523 .ta \w'default  'u +\w'uk-mmdf-workers  'u +\w'action  'u +\w'result  'u
 524 #\fIfield\fR    \fIpattern\fR   \fIaction\fR    \fIresult\fR    \fIstring\fR
 525 # lines starting with a '#' are ignored, as are blank lines
 526 #
 527 # file mail with mmdf2 in the \*(lqTo:\*(rq line into file mmdf2.log
 528 To      mmdf2   file    A       mmdf2.log
 529 # Messages from mmdf pipe to the program err-message-archive
 530 From    mmdf    pipe    A       err-message-archive
 531 # Anything with the \*(lqSender:\*(rq address \*(lquk-mmdf-workers\*(rq
 532 # file in mmdf2.log if not filed already
 533 Sender  uk-mmdf-workers file    ?       mmdf2.log
 534 # \*(lqTo:\*(rq unix \- put in file unix-news
 535 To      Unix    >       A       unix-news
 536 # if the address is jpo=mmdf \- pipe into mmdf-redist
 537 addr    jpo=mmdf        |       A       mmdf-redist
 538 # if the address is jpo=ack \- send an acknowledgement copy back
 539 addr    jpo=ack |       R       \*(lqresend\0\-r\0$(reply-to)\*(rq
 540 # anything from steve \- destroy!
 541 From    steve   destroy A       \-
 542 # anything not matched yet \- put into mailbox
 543 default \-      >       ?       mailbox
 544 # always run rcvalert
 545 *       \-      |       R       rcvalert
 546 .re
 547 .in -.5i
 548 .fi
 549 .\}
 550 .if '\*(ZS'mmdfII' \{\
 551 See \fImaildelivery\fR\0(5) for the details.
 552 .\}
 553
 554 Four programs are currently standardly available,
 555 d52 1
 556 a52 1
 557 Its use is obsoleted by the \fI\&.maildelivery\fR.
 558 d80 1
 559 a80 43
 560 .if '\*(ZS'slocal' \{\
 561 rcvstore (1), mh\-format(5)
 562 .\}
 563 .if '\*(ZS'mmdfII' \{\
 564 rcvstore (1), maildelivery(5), mh\-format(5)
 565 .\}
 566 .Co
 567 None
 568 .if '\*(ZS'slocal' \{\
 569 .Hi
 570 For compatibility with older versions of \fIMH\fR,
 571 if \fIslocal\fR can't find the user's \fI\&.maildelivery\fR file,
 572 it will attempt to execute an old\-style rcvmail hook in the user's $HOME
 573 directory.
 574 In particular,
 575 it will first attempt to execute
 576
 577 .ti +.5i
 578 \&.mh\(rureceive file maildrop directory user
 579
 580 failing that it will attempt to execute
 581
 582 .ti +.5i
 583 $HOME/bin/rcvmail user file sender
 584
 585 before giving up and writing to the user's maildrop.
 586
 587 In addition,
 588 whenever a hook or process is invoked,
 589 file\-descriptor three (3) is set to the message in addition to the standard
 590 input.
 591
 592 @@BEGIN: MMDFIMTS
 593 In addition to an exit status of zero,
 594 the \fIMMDF\fR values \fIRP_MOK\fR (32) and \fIRP_OK\fR (9)
 595 mean that the message has been fully delivered.
 596 All other non\-zero exit status,
 597 including abnormal termination,
 598 is interpreted as the \fIMMDF\fR value \fIRP_MECH\fR (200),
 599 which means \*(lquse an alternate route\*(rq
 600 (deliver the message to the maildrop).
 601 @@END: MMDFIMTS
 602 .\}
 603 a82 10
 604
 605 .if '\*(ZS'mmdfII' \{\
 606 Versions of \fIMMDF\fR with the \fImaildelivery\fR mechanism aren't
 607 entirely backwards\-compatible with earlier versions.
 608 If you have an old\-style hook, the best you can do is to have a one\-line
 609 \fI\&.maildelivery\fR file:
 610
 611 .ti +.15i
 612 default \- pipe A \*(lqbin/rcvmail $(address) $(info) $(sender)\*(rq
 613 .\}
 614 @
 615
 616
 617 1.9
 618 log
 619 @add "mbox" option
 620 @
 621 text
 622 @d2 1
 623 a2 1
 624 .\" @@(#)$Id: mhook.rf,v 1.8 1990/04/05 22:18:43 sources Exp jromine $
 625 d66 1
 626 a66 1
 627     \*(lq| @@(MHETCPATH)/slocal -user $USER\*(rq
 628 @
 629
 630
 631 1.8
 632 log
 633 @rcvtty fixes
 634 @
 635 text
 636 @d2 1
 637 a2 1
 638 .\" @@(#)$Id: mhook.rf,v 1.7 90/04/05 22:12:11 sources Exp Locker: sources $
 639 d119 2
 640 a120 1
 641 The standard maildrop delivery process is used.
 642 d131 7
 643 @
 644
 645
 646 1.7
 647 log
 648 @rcvtty docs
 649 @
 650 text
 651 @d2 1
 652 a2 1
 653 .\" @@(#)$Id: mhook.rf,v 1.6 90/04/05 15:13:25 sources Exp Locker: sources $
 654 d39 6
 655 a44 1
 656 \%[command\ ...]
 657 d310 1
 658 a310 1
 659 to override the default scan listing output format.
 660 @
 661
 662
 663 1.6
 664 log
 665 @add ID
 666 @
 667 text
 668 @d2 1
 669 a2 1
 670 .\" @@(#)$Id:$
 671 d299 1
 672 a299 1
 673 and gives the resulting output to the terminal access daemon for display
 674 d301 1
 675 a301 3
 676 If the terminal access daemon is unavailable on your system,
 677 then \fIrcvtty\fR will write the output to your terminal
 678 if, and only if, your terminal has \*(lqworld\-writable\*(rq permission.
 679 d303 15
 680 a317 2
 681 then the \fIrcvtty\fR program will give a one\-line scan listing
 682 to the terminal access daemon.
 683 d324 1
 684 a324 1
 685 rcvstore (1)
 686 d327 1
 687 a327 1
 688 rcvstore (1), maildelivery(5)
 689 @
 690
 691
 692 1.5
 693 log
 694 @put things back, do .NA stuff another way
 695 @
 696 text
 697 @d2 1
 698 @
 699
 700
 701 1.4
 702 log
 703 @docunemt "N" flag
 704 @
 705 text
 706 @d2 2
 707 a3 2
 708 .TH MHOOK 1 @@(MHCENTERFOOT) @@(MHLEFTFOOT)
 709 .SH .NA
 710 d5 1
 711 a5 1
 712 .SH .SY
 713 @
 714
 715
 716 1.3
 717 log
 718 @typo
 719 @
 720 text
 721 @d202 1
 722 a202 1
 723 If the action succeeded, then the message is considered delivered.
 724 d215 8
 725 a222 1
 726 If the action succeeded, then the message is considered delivered.
 727 @
 728
 729
 730 1.2
 731 log
 732 @fixup for makewhatis
 733 @
 734 text
 735 @d2 1
 736 a2 1
 737 .TH MHOOK 1 [mh.6] MH
 738 @
 739
 740
 741 1.1
 742 log
 743 @Initial revision
 744 @
 745 text
 746 @d2 2
 747 a3 2
 748 .SC MHOOK 1
 749 .NA
 750 d5 1
 751 a5 1
 752 .SY
 753 @