build: Better Build System

1 files changed, 517 insertions, 0 deletions

diff --git a/static/unix-v10/man4/mailsurr.4 b/static/unix-v10/man4/mailsurr.4
new file mode 100644
index 00000000..2caef904
--- /dev/null
+++ b/static/unix-v10/man4/mailsurr.4
@@ -0,0 +1,517 @@
+'\"macro stdmacro
+.if n .pH g4.mailsurr %W% of %G%
+.\"  Emphasis
+.de Em
+\f2\\$1\fP\\$2
+..
+.nr X
+.if \nX=0 .ds x} mailsurr 4 "Essential Utilities" "\&"
+.if \nX=1 .ds x} mailsurr 4 "Essential Utilities"
+.if \nX=2 .ds x} mailsurr 4 "" "\&"
+.if \nX=3 .ds x} mailsurr "" "" "\&"
+.TH \*(x}
+.SH NAME
+\f4mailsurr\f1 \- surrogate commands for routing and transport of mail
+.SH DESCRIPTION
+The \f4mailsurr\f1 file contains routing and transport surrogate
+commands used by the \f4mail\fP command.
+Each entry in \f4mailsurr\f1 has three whitespace-separated,
+single quote delimited fields:
+.P
+.RS
+.ft 4
+\&'\f2sender\fP'   '\f2recipient\fP'   '\f2command\fP'
+.ft 1
+.RE
+.P
+or a line that begins
+.P
+.RS
+.ft 4
+Defaults:
+.ft 1
+.RE
+.P
+Entries and fields may span multiple lines,
+but leading whitespace on field continuation lines is ignored.
+Fields must be less than 1024 characters long after expansion (see
+below).
+.PP
+The sender and recipient fields are regular expressions.
+If the sender and recipient fields match those of the message currently
+being processed, the associated command is invoked.
+.PP
+The \f2command\fP field may have one of the following five forms:
+.P
+.RS
+.ft 4
+.nf
+\f4A\f1[\f4ccept\f1]
+\f4D\f1[\f4eny\f1]
+\f4T\f1[\f4ranslate\f1] \f4R=\f1[\f4\(bv\f1]\f2string\f1
+\f4< S=...;C=...;F=...;\f2 command\f1
+\f4>\fP \f2command\f1
+.fi
+.ft 1
+.RE
+.SS "Regular Expressions"
+The sender and recipient fields are composed of regular
+expressions (REs) which are digested by the \f4regexp\fP(5)
+\f4compile\fP and \f4advance\fP procedures
+in the C library.
+The regular expressions matched are those from \f4ed\fP(1), with simple
+parentheses \f4()\fP playing the role of \f4\e(\e)\fP and the addition of
+the \f4+\fP and \f4?\fP operators from \f4egrep\fP(1).
+Any single quotes embedded within the REs
+.Em must
+be escaped by prepending them with a backslash or
+the RE is not interpreted properly.
+.PP
+The \f4mail\fP command prepends a circumflex (\f4^\f1)
+to the start and appends a dollar sign (\f4$\f1) to the
+end of each RE so that it matches the entire string.
+Therefore it would be an error
+to use \f4^\f2RE\f4$\f1 in the sender and recipient fields.
+To provide case insensitivity, all REs are
+converted to lower case before compilation,
+and all sender and recipient information is converted to
+lower case before comparison.
+This conversion is done only for the purposes of RE pattern matching;
+the information contained within the
+message's header is
+.Em not
+modified.
+.PP
+The sub-expression pattern matching capabilities of \f4regexp\fP may be used
+in the command field,
+that is, \f4(\f1...\f4)\f1, where 1 \(<= \f2n\fP \(<= 9.
+Any occurrences of \f4\e\e\f2n\f1 in the
+replacement string are themselves replaced by the corresponding \f4(\f1...\f4)\f1
+substring in the matched pattern.
+The sub-expression fields from both the sender and recipient fields are
+accessible, with the fields numbered 1 to 9 from left to right.
+.SS "Accept and Deny Commands"
+\f4Accept\fP instructs \f4rmail\fP to continue its processing with the \f4mailsurr\f1
+file,
+but to ignore any subsequent matching \f4Deny\fP.
+That is, unconditionally accept this message for delivery processing.
+\f4Deny\fP instructs \f4rmail\fP to stop processing the \f4mailsurr\f1 file
+and to send a negative delivery notification to the originator of the message.
+Whichever is encountered first takes precedence.
+.SS "Translate Command"
+\f4Translate\fP allows optional on-the-fly translation of recipient address
+information.
+The \f2recipient\fP replacement string is specified as \f4R=\f2string\f1.
+.PP
+For example, given a command line of the form
+.P
+.RS 2
+.nf
+\f4\&'.+' '([^!]+)@(.+)\e.EUO\e.ATT\e.com' 'Translate R=attmail!\e\e2!\e\e1'\f1
+.fi
+.RE
+.P
+and a recipient address of \f4rob@sysa.EUO.ATT.COM\fP
+the resulting recipient address would be \f4attmail!sysa!rob\fP.
+.PP
+Should the first character after the equal sign be a `\(bv',
+the remainder of the string is taken as a command line
+to be directly executed by \f4rmail\fP.
+If any \f4sh\fP(1) syntax is required
+(metacharacters, redirection, etc.),
+then the surrogate command must be of the form:
+.P
+.RS
+\f4sh \-c "\f2shell command line...\f4"\f1
+.RE
+.P
+Special care must be taken to escape properly any embedded back-slashes
+and single or double quotes,
+since \f4rmail\fP uses double quoting to group
+whitespace delimited fields that are meant to be considered as a single
+argument to \f4execl\fP(2).
+It is assumed that the executed command will write one or more replacement
+strings on \f4stdout\fP, one per line.
+If more than one line is returned,
+each is assumed to be a different recipient for the message.
+This mechanism is useful for mailing list expansions.
+As stated above, any occurrences of \f4\e\e\f2n\f1 are replaced by the
+appropriate substring
+.Em before
+the command is executed.
+If the invoked command does not return at least one replacement string
+(no output or just a newline),
+the original string is
+.Em not
+modified.
+For example, the command line
+.P
+.RS
+\f4\&'.+'	'(.+)' 'Translate R=\(bv/usr/bin/findpath \e\e1'\fP
+.RE
+.P
+allows local routing decisions to be made.
+.PP
+If the recipient address string is modified, \f4mailsurr\fP
+is rescanned from the beginning with the new address(es),
+and any prior determination of \f4Accept\fP (see above) is discarded.
+.SS "\f4<\fP \f2command\fP"
+The intent of a \f4<\fP command is that it is invoked as part of the transport
+and delivery mechanism,
+with the ready-for-delivery message available to the command
+at its standard input.
+As such, there are three conditions possible when the command exits:
+.RS
+.TP 10
+Success
+The command successfully delivered the message.
+What actually constitutes successful delivery may be different
+within the context of different surrogates.
+The \f4rmail\fP process assumes that no more processing
+is required for the message for the current recipient.
+.TP 10
+Continue
+The command performed some function
+(logging remote message traffic, for example)
+but did not do what would be considered message delivery.
+The \f4rmail\fP process continues to scan the
+\f4mailsurr\f1 file looking for some
+other delivery mechanism.
+.TP 10
+Failure
+The command encountered some catastrophic failure.
+The \f4rmail\fP process
+stops processing the message and sends to the originator of the message
+a non-delivery notification that includes any \f4stdout\fP and \f4stderr\fP
+output generated by the command.
+.RE
+.PP
+The semantics of the \f4<\fP command field in the \f4mailsurr\fP file allow
+the specification of exit codes that constitute success, continue, and
+failure for each surrogate command individually.
+The syntax of the exit state specification is:
+.P
+.RS
+.nf
+\f4<\f1 WS [\f2exit_state_id\f4=\f2ec\f1[\f4,\f2ec\f1[,...]]\f4;\f1][\f2exit_state_id\f4=\f2ec\f1[,\f2ec\f1[,...]]\f4;\f1
+        [...]]] WS\0\f2surrogate_cmd_line\f1
+.fi
+.RE
+.P
+.SM 
+.I WS
+is whitespace.
+\f2exit_state_id\fP can have the value \f4S\fP, \f4C\fP, or \f4F\fP.
+\f2exit_state_id\fPs can be specified in any order.
+\f2ec\fP can
+be:
+.IP
+any integer 0 \(<= \f2n\fP \(<= 255
+[Negative exit values are not possible.
+See \f4exit\fP(2) and \f4wait\fP(2).]
+.IP
+a range of integers of the form \f2lower_limit\f1\-\f2upper_limit\f1
+where the limits are \(>= 0 and \(<= 255, and
+.IP
+\f4\(**\fP, which implies \f2anything\fP
+.PP
+For example, a command field of the form:
+.P
+.RS
+\&'\f4< S=1-5,99;C=0,12;F=\(**;   \f2command\fP %R'\f1
+.RE
+.P
+indicates that exit values of 1 through 5, and 99,
+are to be considered success,
+values of 0 (zero) and 12 indicate continue,
+and that anything else implies failure.
+If not explicitly supplied, default settings are \f4S=0;C=\(**;\fP.
+.PP
+It may be possible for ambiguous entries to exist
+if two exit states have the same
+value, for example,  \f4S=12,23;C=\(**;F=23,52\fP; or \f4S=\(**;C=9;F=\(**;\fP.
+To account for this, \f4rmail\fP looks for
+.Em explicit
+exit
+values (that is,
+.Em not
+\&``\(**'') in
+order of success, continue, failure.
+Not finding an explicit match,
+\f4rmail\fP then scans for ``\(**'' in the same order.
+.PP
+It is possible to eliminate an exit state completely by setting that
+state's value to an impossible number.
+Since exit values must be between 0 and 255 (inclusive),
+a value of 256 is a good one to use.
+For example, if you had a surrogate command that was to log all message
+traffic, a \f4mailsurr\f1 entry of
+.P
+.RS 2
+.nf
+\f4\&'(.+)'\0'(.+)'\0'\f4<\fPS=256;C=*;\0/usr/lib/mail/surrcmd/logger \e\e1 \e\e2'\f1
+.fi
+.RE
+.P
+would always indicate continue.
+.PP
+Surrogate commands are executed by \f4rmail\fP directly.
+If any shell syntax is required
+(metacharacters, redirection, etc.),
+then the surrogate command must be of the form:
+.P
+.RS
+\f4sh \-c "\f2shell command line...\f4"\f1
+.RE
+.P
+Special care must be taken to properly escape any embedded
+back-slashes and other characters special to the shell
+as stated in the ``Translate'' section above.
+.PP
+If there are no matching \f4<\fP commands,
+or all matching \f4<\fP commands exit with a continue indication,
+\f4rmail\fP attempts to deliver the message itself by assuming
+that the recipient is local and delivering
+the message to \f4/var/mail/\fP\f2recipient\fP.
+.SS "\f4>\f1 command"
+The intent of a \f4>\fP command is that it is invoked
+.Em after
+a successful delivery to do any post-delivery processing that may be required.
+Matching \f4>\fP commands are executed only if some \f4<\fP command indicates a
+successful delivery (see the previous section)
+or local delivery processing is successful.
+The \f4mailsurr\f1 file is rescanned and
+all matching \f4>\fP commands,
+not just those following the successful \f4<\fP command,
+are executed in order.
+The exit status of an \f4>\fP command is ignored.
+.SS "Defaults: Line"
+The default settings may be redefined by creating a separate
+line in the \f4mailsurr\f1 file of the form
+.P
+.RS
+.nf
+\f4Defaults: \f1[\f4S=\f1...\f4;\f1][\f4C=\f1...\f4;\f1][\f4F\f1=...\f4;\f1]
+.fi
+.ft 1
+.RE
+.P
+\f4Defaults:\fP lines are honored and the indicated default values
+redefined when the line is encountered during the normal processing
+of the \f4mailsurr\f1 file.
+Therefore, to redefine the defaults globally, the \f4Defaults:\fP
+line should be the first line in the file.
+It is possible to have multiple \f4Defaults:\fP lines in the \f4mailsurr\f1 file,
+where each subsequent line overrides the previous one.
+.SS "Surrogate Command Keyword Replacement."
+Certain special sequences are textually-substituted
+in surrogate commands before they are invoked:
+.P
+.RS
+.PD 0
+.TP 11
+\f4%n\f1
+the recipient's full name.
+.TP
+\f4%R\f1
+the full return path to the originator (useful for sending replies,
+delivery failure notifications, etc.)
+.TP
+\f4%c\f1
+value of the \f5Content-Type:\fP header line if present.
+.TP
+\f4%C\f1
+\&``\f5text\fP'' or ``\f5binary\fP'', depending on an actual scan of the content.
+This is independent of the value of any \f5Content-Type\fP header line encountered
+(useful when calling \f4ckbinarsys\fP.)
+.TP
+\f4%S\f1
+the value of the \f5Subject:\fP header line, if present.
+.TP
+\f4%l\f1
+value of the \f5Content-Length:\fP header line.
+.TP
+\f4%L\f1
+the local system name.
+This will be either \f4CLUSTER\fP from \f4mailcnfg\fP or the value returned
+by \f4uname\fP.
+.TP
+\f4%U\f1
+the local system name, as returned by \f4uname\fP.
+.TP
+\f4%X\f1
+the value of \f4SMARTERHOST\fP in \f4mailcnfg\fP.
+.TP
+\f4%D\f1
+the local domain name.
+This will be either \f4DOMAIN\fP from \f4mailcnfg\fP, or the value returned by
+\f4getdomainame\fP.
+.TP
+\f4\e\e\f2n\f1
+as described above, the corresponding (...)
+substring in the matched patterns.
+This implies that the \f4regexp\fP limitation of 9 substrings is applied
+to the sender and recipient REs collectively.
+.TP
+\f4%\f2keywords\f1
+Other keywords as specified in \f4/etc/mail/mailcnfg\fP.
+See \f4mailcnfg\fP(4).
+.RE
+The sequences \f4%L\fP, \f4%U\fP, \f4%D\fP, and \f4%\f2keywords\f1 are
+permitted within the sender and recipient fields as well as in the command
+fields.
+.PD
+.PP
+An example of the \f4mailsurr\f1 entry that replaces the
+\f4uux\fP ``built-in'' of previous versions of \f4rmail\fP is:
+.P
+.RS
+.nf
+\f4\&'.+'	'([^@!]+)!(.+)'	'< /usr/bin/uux \- \e\e1!rmail (\e\e2)'\fP
+.fi
+.RE
+.SS "Mail Surrogate Examples"
+Some examples of mail surrogates include the distribution of message-waiting
+notifications to LAN-based recipients and lighting Message-Waiting Lamps,
+the ability to mail output to printers,
+and the logging of all \f4rmail\fP requests between remote systems
+(messages passing through the local system).
+The following is a sample \f4mailsurr\f1 file:
+.P
+.nf
+.ft 4
+\s-1#
+# Some common remote mail surrogates follow. To activate any
+# or all of them, remove the `#' (comment indicators) from
+# the beginning of the appropriate lines. Remember that they
+# will be tried in the order they are encountered in the file,
+# so put preferred surrogates first.
+  
+#	Prevent all shell meta-characters
+\&'.+'	'.*[`;&|^<>()].*'       'Deny'
+  
+#	Map all names of the form local-machine!user -> user
+\&'.+'	'%L!(.+)'               'Translate R=\\1'
+  
+#	Map all names of the form uname!user -> user
+#	Must be turned on when using mail in a cluster environment.
+#'.+'	'%U!(.+)'               'Translate R=\\1'
+  
+#	Map all names of the form user@host -> host!user
+\&'.+'	'([^!@]+)@(.+)'         'Translate R=\\2!\\1'
+  
+#	Map all names of the form host.uucp!user -> host!user
+\&'.+'	'([^!@]+)\\.uucp!(.+)'  'Translate R=\\1!\\2'
+  
+#	Map all names of the form host.local-domain!user -> host!user
+#	DOMAIN= within /etc/mail/mailcnfg will override getdomainame(3).
+\&'.+'	'([^!@]+)%D!(.+)'       'Translate R=\\1!\\2'
+  
+#	Allow access to `attmail' from remote system `sysa'
+\&'sysa!.*'	'attmail!.+'    'Accept'
+  
+#	Deny access to `attmail' from all other remotes	
+\&'.+!.+'	'attmail!.+'    'Deny'
+  
+#	Send mail for `laser' to attached laser printer
+#	Make certain that failures are reported via return mail.
+\&'.+'	'laser'	'\f4<\fP S=0;F=*; lp \-dlaser'
+  
+#	Run all local names through the mail alias processor
+#
+\&'.+'	'[^!@]+'         'Translate R=|/usr/bin/mailalias %n'
+  
+#	For remote mail via nusend
+#'.+'	'([^!]+)!(.+)'   '\f4<\fP /usr/bin/nusend \-d \e\e1 \-s \-e \-!"rmail \e\e2" \-'
+  
+#	For remote mail via usend
+\&'.+'	'([^!]+)!(.+)'
+         '\f4<\fP /usr/bin/usend \-s \-d\e\e1 \-uNoLogin \-!"rmail \e\e2" \- '
+  
+#	For remote mail via uucp
+\&'.+'	'([^!@]+)!.+'   '\f4<\fPS=256;C=0;
+  		/usr/lib/mail/surrcmd/ckbinarsys \-t %C \-s \e\e1'
+\&'.+'	'([^!@]+)!(.+)'   '\f4<\fP /usr/bin/uux \- \e\e1!rmail (\e\e2)'
+  
+#	For remote mail via smtp
+#'.+'	'([^!@]+)!(.+)'         '< /usr/lib/mail/surrcmd/smtpqer %R %n'
+  
+#	If none of the above work, then let a router change the address.
+#'.+'	'.*[!@].*'      'Translate R=| /usr/lib/mail/surrcmd/smail -A %n'
+  
+#	If none of the above work, then ship remote mail off to a smarter host.
+#	Make certain that SMARTERHOST= is defined within /etc/mail/mailcnfg.
+#'.+'	'.*[!@].*'              'Translate R=%X!%n'
+  
+#	Log successful message deliveries
+\&'(.+)' '(.+)' '\f4>\fP/usr/lib/mail/surrcmd/logger \\1 \\2'\s0
+.ft 1
+.fi
+.PP
+Note that invoking \f4mail\fP to read mail does not
+involve the \f4mailsurr\f1 file or any surrogate processing.
+.SS "Security"
+Surrogate commands execute
+with the permissions of \f4rmail\fP (user \s-1ID\s+1 of the invoker,
+group \s-1ID\s+1 of mail).
+This allows surrogate commands to validate themselves,
+checking that their effective group \s-1ID\s+1 was \f4mail\fP at invocation time.
+This requires that all additions to \f4mailsurr\f1 be scrutinized before
+insertion to prevent any unauthorized access to users' mail files.
+All surrogate commands are executed with the path
+\f4/usr/lib/mail/surrcmd:/usr/bin\fP.
+.SS "Debugging New \f4mailsurr\f1 Entries"
+To debug \f4mailsurr\fP files,
+use the \f4\-T\fP option of the \f4mail\fP command.
+The \f4\-T\fP option requires an argument that is taken as the
+pathname of a test \f4mailsurr\fP file.
+If null (as in \f4\-T ""\fP),
+the system \f4mailsurr\f1 file is used.
+Enter
+.P
+.RS
+.nf
+\f4mail\ \-T \f2test_file\0recipient\f1
+.fi
+.RE
+.P
+and some trivial message (like ``\f4testing\fP''),
+followed by a line with either just a dot (``\f4.\fP'') or a cntl-D.
+The result of using the \f4\-T\fP option is displayed on standard output and
+shows the inputs and resulting transformations as \f4mailsurr\f1 is
+processed by the \f4mail\fP command for the indicated \f2recipient\fP.
+.PP
+Mail messages will never be sent or delivered when using the \f4\-T\fP option.
+.SH "FILES"
+.PD 0
+.TP 27
+\f4/etc/mail/mailsurr\fP
+.TP 27
+\f4/usr/lib/mail/surrcmd/\(**\fP
+surrogate commands
+.TP 27
+\f4/etc/mail/mailcnfg\fP
+initialization information for \f4mail\fP
+.PD
+.SH SEE ALSO
+\f4ckbinarsys\fP(1M),
+\f4mailcnfg\fP(4)
+.br
+\f4mail\fP(1),
+\f4sh\fP(1),
+\f4uux\fP(1),
+\f4ed\fP(1),
+\f4egrep\fP(1),
+in the \f2User's Reference Manual\f1
+.br
+\f4exec\fP(2),
+\f4exit\fP(2),
+\f4wait\fP(2),
+\f4popen\fP(3),
+\f4regexp\fP(5),
+\f4getdomainname\f1(3)
+in the \f2Programmer's Reference Manual\f1
+.SH "NOTES"
+It would be unwise to install new entries into the system
+\f4mailsurr\f1 file without verifying at least their syntactical
+correctness via `\f4mail\fP \f4\-\T\fP \f2...\fP' as described above.