Return to mhook.rf CVS log

Up to [CSRG BSD Unix] / 43BSD / contrib / mh / conf / doc

Annotation of 43BSD/contrib/mh/conf/doc/mhook.rf, revision 1.1

1.1     ! root        1: .\"    @(MHWARNING)
        !             2: .TH MHOOK 1 "April 22, 1986" MH [mh.6]
        !             3: .UC 6
        !             4: .SH NAME
        !             5: mhook \- MH receive\-mail hooks
        !             6: .SH SYNOPSIS
        !             7: .in +.5i
        !             8: .ti -.5i
        !             9: $HOME/\&.maildelivery
        !            10: @BEGIN: MHMTS
        !            11: .ds SL \fIpost\fR
        !            12: .ds ZS slocal
        !            13: @END: MHMTS
        !            14: @BEGIN: MMDFIMTS
        !            15: .ds SL \fIslocal\fR
        !            16: .ds ZS slocal
        !            17: @END: MMDFIMTS
        !            18: @BEGIN: MMDFIIMTS
        !            19: .ds SL the local channel
        !            20: .ds ZS mmdfII
        !            21: @END: MMDFIIMTS
        !            22: @BEGIN: SENDMTS
        !            23: .ds SL \fIslocal\fR
        !            24: .ds ZS slocal
        !            25: @END: SENDMTS
        !            26: 
        !            27: .ti .5i
        !            28: @(MHETCPATH)/rcvdist
        !            29: \%[\-form\ formfile]
        !            30: \%[switches\ for\ \fIpostproc\fR]
        !            31: address\ ...
        !            32: \%[\-help]
        !            33: 
        !            34: .ti .5i
        !            35: @(MHETCPATH)/rcvpack
        !            36: file
        !            37: \%[\-help]
        !            38: 
        !            39: .ti .5i
        !            40: @(MHETCPATH)/rcvtty
        !            41: \%[command\ ...]
        !            42: \%[\-help]
        !            43: .in -.5i
        !            44: .SH DESCRIPTION
        !            45: A receive\-mail hook is a program that is run whenever you receive a
        !            46: mail message.
        !            47: You do \fBNOT\fR invoke the hook yourself,
        !            48: @BEGIN: MHMTS
        !            49: rather the hook is invoked on your behalf by \fIMH\fR.
        !            50: @END: MHMTS
        !            51: @BEGIN: MMDFIMTS
        !            52: rather the hook is invoked on your behalf by \fIMMDF\fR
        !            53: when you (symbolically) link @(MHETCPATH)/slocal to the file
        !            54: bin/rcvmail in your home directory.
        !            55: @END: MMDFIMTS
        !            56: @BEGIN: MMDFIIMTS
        !            57: rather the hook is invoked on your behalf by \fIMMDF\fR.
        !            58: @END: MMDFIIMTS
        !            59: @BEGIN: SENDMTS
        !            60: rather the hook is invoked on your behalf by \fISendMail\fR,
        !            61: when you include the line
        !            62: .nf
        !            63: .in +.5i
        !            64:     \*(lq| @(MHETCPATH)/slocal\*(rq
        !            65: .in -.5i
        !            66: .fi
        !            67: in your \&.forward file in your home directory.
        !            68: @END: SENDMTS
        !            69: 
        !            70: The \fI\&.maildelivery\fR file,
        !            71: which is an ordinary ASCII file,
        !            72: controls how local delivery is performed.
        !            73: This file is read by \*(SL.
        !            74: .if '\*(ZS'slocal' \{\
        !            75: 
        !            76: The format of each line in the \fI\&.maildelivery\fR file is
        !            77: 
        !            78: .ti +.5i
        !            79: \fBfield pattern action result string\fR
        !            80: 
        !            81: where
        !            82: 
        !            83: .in +.5i
        !            84: .ti -.25i
        !            85: \fBfield\fR:
        !            86: .br
        !            87: The name of a field that is to be searched for a pattern.
        !            88: This is any field in the headers of the message that might be present.
        !            89: In addition, the following special fields are also defined:
        !            90: .in +.25i
        !            91: \fIsource\fR: the out\-of\-band sender information
        !            92: .br
        !            93: \fIaddr\fR: the address that was used to cause delivery to the recipient
        !            94: .br
        !            95: \fIdefault\fR: this matches \fIonly\fR if the message hasn't been delivered yet
        !            96: .br
        !            97: \fI*\fR: this always matches
        !            98: .in -.25i
        !            99: 
        !           100: .ti -.25i
        !           101: \fBpattern\fR:
        !           102: .br
        !           103: The sequence of characters to match in the specified field.
        !           104: Matching is case\-insensitive but not RE\-based.
        !           105: 
        !           106: .ti -.25i
        !           107: \fBaction\fR:
        !           108: .br
        !           109: The action to take to deliver the message.
        !           110: This is one of
        !           111: 
        !           112: .in +.5i
        !           113: .ti -.5i
        !           114: \fIfile\fR or \fI>\fR:
        !           115: .br
        !           116: Append the message to the file named by \fBstring\fR.
        !           117: The standard maildrop delivery process is used.
        !           118: If the message can be appended to the file,
        !           119: then this action succeeds.
        !           120: 
        !           121: When writing to the file,
        !           122: a new field is added:
        !           123: 
        !           124: .ti +.5i
        !           125: Delivery\-Date:\ date
        !           126: 
        !           127: which indicates the date and time that message was appended to the file.
        !           128: 
        !           129: .ti -.5i
        !           130: \fIpipe\fR or \fI|\fR:
        !           131: .br
        !           132: Pipe the message as the standard input to the command named by \fBstring\fR,
        !           133: using the Bourne shell \fIsh\fR\0(1) to interpret the string.
        !           134: Prior to giving the string to the shell,
        !           135: it is expanded with the following built\-in variables:
        !           136: .in +.25i
        !           137: $(sender): the return address for the message
        !           138: .br
        !           139: $(address): the address that was used to cause delivery to the recipient
        !           140: .br
        !           141: $(size): the size of the message in bytes
        !           142: .br
        !           143: $(reply\-to): either the \*(lqReply\-To:\*(rq or \*(lqFrom:\*(rq field
        !           144: of the message
        !           145: .br
        !           146: $(info): miscellaneous out\-of\-band information
        !           147: .in -.25i
        !           148: 
        !           149: When a process is invoked, its environment is:
        !           150: the user/group id:s are set to recipient's id:s;
        !           151: the working directory is the recipient's directory;
        !           152: the umask is 0077;
        !           153: the process has no /dev/tty;
        !           154: the standard input is set to the message;
        !           155: the standard output and diagnostic output are set to /dev/null;
        !           156: all other file\-descriptors are closed;
        !           157: the envariables \fB$USER\fR, \fB$HOME\fR, \fB$SHELL\fR are set
        !           158: appropriately,
        !           159: and no other envariables exist.
        !           160: 
        !           161: The process is given a certain amount of time to execute.
        !           162: If the process does not exit within this limit,
        !           163: the process will be terminated with extreme prejudice.
        !           164: The amount of time is calculated as ((size x 60) + 300) seconds,
        !           165: where size is the number of bytes in the message.
        !           166: 
        !           167: The exit status of the process is consulted in determining the success of the
        !           168: action.
        !           169: An exit status of zero means that the action succeeded.
        !           170: Any other exit status (or abnormal termination) means that the action failed.
        !           171: 
        !           172: In order to avoid any time limitations,
        !           173: you might implement a process that began by \fIforking\fR.
        !           174: The parent would return the appropriate value immediately,
        !           175: and the child could continue on,
        !           176: doing whatever it wanted for as long as it wanted.
        !           177: This approach is somewhat risky if the parent is going to return an
        !           178: exit status of zero.
        !           179: If the parent is going to return a non\-zero exit status,
        !           180: then this approach can lead to quicker delivery into your maildrop.
        !           181: 
        !           182: .ti -.5i
        !           183: \fIqpipe\fR or \fI<caret>\fR:
        !           184: .br
        !           185: Similar to \fIpipe\fR,
        !           186: but executes the command directly,
        !           187: after built\-in variable expansion,
        !           188: without assistance from the shell.
        !           189: 
        !           190: .ti -.5i
        !           191: \fIdestroy\fR:
        !           192: .br
        !           193: This action always succeeds.
        !           194: .in -.5i
        !           195: 
        !           196: .ti -.25i
        !           197: \fBresult\fR:
        !           198: .br
        !           199: Indicates how the action should be performed:
        !           200: 
        !           201: .in +.5i
        !           202: .ti -.5i
        !           203: \fIA\fR:
        !           204: .br
        !           205: Perform the action.
        !           206: If the action succeeded, then the message is considered delivered.
        !           207: 
        !           208: .ti -.5i
        !           209: \fIR\fR:
        !           210: .br
        !           211: Perform the action.
        !           212: Regardless of the outcome of the action,
        !           213: the message is not considered delivered.
        !           214: 
        !           215: .ti -.5i
        !           216: \fI?\fR:
        !           217: .br
        !           218: Perform the action only if the message has not been delivered.
        !           219: If the action succeeded, then the message is considered delivered.
        !           220: .in -.5i
        !           221: .in -.5i
        !           222: 
        !           223: The file is always read completely,
        !           224: so that several matches can be made and several actions can be taken.
        !           225: The \fI\&.maildelivery\fR file must be owned either by the user or by root,
        !           226: and must be writable only by the owner.
        !           227: If the \fI\&.maildelivery\fR file can not be found,
        !           228: or does not perform an action which delivers the message,
        !           229: then the file @(MHETCPATH)/maildelivery is read according to the same rules.
        !           230: This file must be owned by the root and must be writable only by the root.
        !           231: If this file can not be found
        !           232: or does not perform an action which delivers the message,
        !           233: then standard delivery to the user's maildrop, @(MHDROPLOC), is performed.
        !           234: 
        !           235: Arguments in the \fI\&.maildelivery\fR file are separated by white\-space or
        !           236: comma.
        !           237: Since double\-quotes are honored,
        !           238: these characters may be included in a single argument by enclosing the
        !           239: entire argument in double\-quotes.
        !           240: A double\-quote can be included by preceeding it with a backslash.
        !           241: 
        !           242: To summarize, here's an example:
        !           243: 
        !           244: .nf
        !           245: .in +.5i
        !           246: .ta \w'default  'u +\w'uk-mmdf-workers  'u +\w'action  'u +\w'result  'u
        !           247: #\fIfield\fR   \fIpattern\fR   \fIaction\fR    \fIresult\fR    \fIstring\fR
        !           248: # lines starting with a '#' are ignored, as are blank lines
        !           249: #
        !           250: # file mail with mmdf2 in the \*(lqTo:\*(rq line into file mmdf2.log
        !           251: To     mmdf2   file    A       mmdf2.log
        !           252: # Messages from mmdf pipe to the program err-message-archive
        !           253: From   mmdf    pipe    A       err-message-archive
        !           254: # Anything with the \*(lqSender:\*(rq address \*(lquk-mmdf-workers\*(rq
        !           255: # file in mmdf2.log if not filed already
        !           256: Sender uk-mmdf-workers file    ?       mmdf2.log
        !           257: # \*(lqTo:\*(rq unix \- put in file unix-news
        !           258: To     Unix    >       A       unix-news
        !           259: # if the address is jpo=mmdf \- pipe into mmdf-redist
        !           260: addr   jpo=mmdf        |       A       mmdf-redist
        !           261: # if the address is jpo=ack \- send an acknowledgement copy back
        !           262: addr   jpo=ack |       R       \*(lqresend\0\-r\0$(reply-to)\*(rq
        !           263: # anything from steve \- destroy!
        !           264: From   steve   destroy A       \-
        !           265: # anything not matched yet \- put into mailbox
        !           266: default        \-      >       ?       mailbox
        !           267: # always run rcvalert
        !           268: *      \-      |       R       rcvalert
        !           269: .re
        !           270: .in -.5i
        !           271: .fi
        !           272: .\}
        !           273: .if '\*(ZS'mmdfII' \{\
        !           274: See \fImaildelivery\fR\0(5) for the details.
        !           275: .\}
        !           276: 
        !           277: Four programs are currently standardly available,
        !           278: \fIrcvdist\fR (redistribute incoming messages to additional recipients),
        !           279: \fIrcvpack\fR (save incoming messages in a \fIpackf\fR'd file),
        !           280: and \fIrcvtty\fR (notify user of incoming messages).
        !           281: The fourth program,
        !           282: \fIrcvstore\fR\0(1) is described separately.
        !           283: They all reside in the \fI@(MHETCPATH)/\fR directory.
        !           284: 
        !           285: The \fIrcvdist\fR program will resend a copy of the message to all of the
        !           286: addresses listed on its command line.
        !           287: It uses the format string facility described in \fImh\-format\fR\0(5).
        !           288: 
        !           289: The \fIrcvpack\fR program will append a copy of the message to the file listed
        !           290: on its command line.
        !           291: Its use is obsoleted by the \fI\&.maildelivery\fR.
        !           292: 
        !           293: The \fIrcvtty\fR program executes the named file with the message as its
        !           294: standard input,
        !           295: and gives the resulting output to the terminal access daemon for display
        !           296: on your terminal.
        !           297: If the terminal access daemon is unavailable on your system,
        !           298: then \fIrcvtty\fR will write the output to your terminal
        !           299: if, and only if, your terminal has \*(lqworld\-writable\*(rq permission.
        !           300: If no file is specified, or is bogus, etc.,
        !           301: then the \fIrcvtty\fR program will give a one\-line scan listing
        !           302: to the terminal access daemon.
        !           303: .Fi
        !           304: ^@(MHETCPATH)/mtstailor~^tailor file
        !           305: ^$HOME/\&.maildelivery~^The file controlling local delivery
        !           306: ^@(MHETCPATH)/maildelivery~^Rather than the standard file
        !           307: .Sa
        !           308: .if '\*(ZS'slocal' \{\
        !           309: rcvstore (1)
        !           310: .\}
        !           311: .if '\*(ZS'mmdfII' \{\
        !           312: rcvstore (1), maildelivery(5)
        !           313: .\}
        !           314: .Co
        !           315: None
        !           316: .if '\*(ZS'slocal' \{\
        !           317: .Hi
        !           318: For compatibility with older versions of \fIMH\fR,
        !           319: if \fIslocal\fR can't find the user's \fI\&.maildelivery\fR file,
        !           320: it will attempt to execute an old\-style rcvmail hook in the user's $HOME
        !           321: directory.
        !           322: In particular,
        !           323: it will first attempt to execute
        !           324: 
        !           325: .ti +.5i
        !           326: \&.mh\(rureceive file maildrop directory user
        !           327: 
        !           328: failing that it will attempt to execute
        !           329: 
        !           330: .ti +.5i
        !           331: $HOME/bin/rcvmail user file sender
        !           332: 
        !           333: before giving up and writing to the user's maildrop.
        !           334: 
        !           335: In addition,
        !           336: whenever a hook or process is invoked,
        !           337: file\-descriptor three (3) is set to the message in addition to the standard
        !           338: input.
        !           339: 
        !           340: @BEGIN: MMDFIMTS
        !           341: In addition to an exit status of zero,
        !           342: the \fIMMDF\fR values \fIRP_MOK\fR (32) and \fIRP_OK\fR (9)
        !           343: mean that the message has been fully delivered.
        !           344: All other non\-zero exit status,
        !           345: including abnormal termination,
        !           346: is interpreted as the \fIMMDF\fR value \fIRP_MECH\fR (200),
        !           347: which means \*(lquse an alternate route\*(rq
        !           348: (deliver the message to the maildrop).
        !           349: @END: MMDFIMTS
        !           350: .\}
        !           351: .Bu
        !           352: Only two return codes are meaningful, others should be.
        !           353: 
        !           354: .if '\*(ZS'mmdfII' \{\
        !           355: Versions of \fIMMDF\fR with the \fImaildelivery\fR mechanism aren't
        !           356: entirely backwards\-compatible with earlier versions.
        !           357: If you have an old\-style hook, the best you can do is to have a one\-line
        !           358: \fI\&.maildelivery\fR file:
        !           359: 
        !           360: .ti +.15i
        !           361: default \- pipe A \*(lqbin/rcvmail $(address) $(info) $(sender)\*(rq
        !           362: .\}
        !           363: .En

This archive runs on limited infrastructure. Preserving old code on modern bandwidth. Automated agents are requested to crawl responsibly.