%% \section{Router}


The {\em router} daemon makes all decisions affecting 
the processing of messages in ZMailer.

A mail message is submitted by placing it in a file in the
{\tt \$POSTOFFICE/router/} directory. The 
{\em router} frequently scans this directory for new 
files and will lock and process them as it finds them. 
The result is a message control file that gets linked into 
the {\tt \$POSTOFFICE/scheduler/} and 
{\tt \$POSTOFFICE/transport/} directories for use 
by the {\em scheduler(8)} in the next step of message 
processing. The original message file is then moved to the 
{\tt \$POSTOFFICE/queue/} directory. 

The {\em router}'s behaviour is controlled by a 
configuration file read at startup. It is really a 
{\em zmsh(1)} script that uses facilities provided 
builtin to the {\em router}. 

{\bf Usage}

Invoking router without any arguments will do nothing
(except make it read its configuration file and promptly
exit). The normal startup method is to run the {\em zmailer(1)} 
script, as in {\tt zmailer router}. This will start the 
{\em router} as a daemon and  kill the previous 
incarnation of the {\em router}. 

{\tt router [ -diksSV ] [ -f configfile ] [ -n \#routers ] [ -o zmshoptions ] [ -t traceflag ] [ -L logfile ] [ -P postoffice ]}
 

{\bf Parameters}

\begin{description}
\item[{\tt -d}] \mbox{}

Detach and run as a daemon. 

\item[{\tt -f configfile}] \mbox{}

Overrides the default configuration 
file {\tt MAILSHARE/router.cf}. 

\item[{\tt -i}] \mbox{}

Run interactively, presenting a {\em zmsh}  
session with the configuration file preloaded. 

\item[{\tt -k}] \mbox{}

Kill the currently running router by 
sending it a {\tt SIGTERM} signal. 

\item[{\tt -L logfile}] \mbox{}

Overrides the default   log file location 
{\tt \$LOGDIR/router/}. 

\item[{\tt -n \#routers}] \mbox{}

Starts the specified number of 
parallel router processes. The default is a single router process. 

\item[{\tt -o zmshoptions}] \mbox{}

Sets the option string passed on the 
internal {\em zmsh} invocation. The default is {\tt -O}. 
Note that the leading `-' is mandatory. See {\em zmsh(1)} 
for the available options. 

\item[{\tt -P postoffice}] \mbox{}

Specifies an alternate 
{\tt \$POSTOFFICE/} directory. 

\item[{\tt -S}] \mbox{}

Can be used to turn off non-serious syslogging. 

\item[{\tt -s}] \mbox{}

Turns stability-flag off and on. Without this
flag, the search of new jobs will be done with (sometimes) 
timeconsuming care of organizing the job files into time order. 

\item[{\tt -t traceflag}] \mbox{}

Sets trace options, one per -t switch, 
even before the configuration file is loaded. This is otherwise 
equivalent to the builtin {\tt trace} command. The currently 
known options are: {\tt assign, bind, compare, db, final, functions, matched, memory, on, regexp, resolv, rewrite, router, and sequencer}. 

\item[{\tt -V}] \mbox{}

Print version message and run interactively. 

\end{description}
 

To restart a {\em router} daemon: 
\begin{alltt}
   router -dk
\end{alltt}


To test an address, start up an interactive session: 
\begin{alltt}
   router -i
\end{alltt}


or if the ZMailer {\em sendmail(8)} is installed: 
\begin{alltt}
   sendmail -bt
\end{alltt}


Then just use the pre-defined functions.




\subsection{ZMSH Script Language}



{\em zmsh} is an implementation of the Bourne shell 
suitable for use with the ZMailer {\em router(8)} as 
its configuration file language interpreter. It contains 
extensions that allow structured data (in the form of lists) 
to be manipulated. 

The shell supports three basic kinds of functions: Unix 
commands, user-defined functions, and builtin commands. 
The latter comes in two variations: normal functions which 
take string arguments and return a status code (much as an 
embedded Unix command would work), and list-manipulation 
functions which understand list arguments and can return 
list arguments. The defined functions can take any form 
of argument and return any form of value (a status code, 
a string, or a list). 

Shell operations (pipes, backquote evaluation and substitution) 
will work between combinations of builtin functions, 
defined functions, and Unix commands.

The shell precompiles its input to a (possibly optimized) 
byte-code form, which is then interpreted as required. 
This means that the original form of the input is not kept 
around {\tt in-core} for future reference. If the input 
is an included file, the shell will try to save the byte-code 
form in a {\tt .fc} file associated with the input file. 
For example, if input is from {\tt file.cf}, the shell 
will try to create {\tt fc/file.fc} and then {\tt file.fc}. 
These files will in turn be searched for and loaded 
(after a consistency check) whenever a {\tt .cf} file is included. 

The effects of input and output redirections are predicted 
prior to the execution of a command and its I/O setup.

{\bf Usage}

{\tt zmsh [ -CILOPRSYaefhinstuvx ] [ -c command ] [ script ...]}



{\bf Parameters}

See the Debugging section for [-CILOPRSY] 
debugging options. 

\begin{description}
\item[{\tt -c command}] \mbox{}

Run the given argument as a shell 
command script. 

\item[{\tt -a}] \mbox{}

Automatically export new or changed shell 
variables.  

\item[{\tt -e}] \mbox{}

Exit on non-zero status return of any command. 

\item[{\tt -f}] \mbox{}

Disables filename generation. 

\item[{\tt -h}] \mbox{}

Hash and cache the location of Unix commands. 
The option is set by default. 

\item[{\tt -i}] \mbox{}

This shell is interactive, meaning prompts 
are printed when ready for more input, {\tt SIGTERM} signal 
is ignored, and the shell does not exit easily. This flag is 
automatically set if {\tt stdin} and {\tt stderr} are 
both attached to a {\tt tty}. 

\item[{\tt -n}] \mbox{}

Read commands but do not execute them. 

\item[{\tt -s}] \mbox{}

Read commands from {\tt stdin}. If there 
are non-option arguments to the shell, the first of these will 
be interpreted as a shell script to open on {\tt stdin}, 
and the rest as arguments to the script. 

\item[{\tt -t}] \mbox{}

Exit after running one command. 

\item[{\tt -u}] \mbox{}

Unset variables produce an error on 
substitution. 

\item[{\tt -v}] \mbox{}

Print shell input as it is read. 

\item[{\tt -x}] \mbox{}

Print commands as they are executed. 

\end{description}





\subsection{Configuration Script Writing Rules}

Text to be inserted here.




\subsection{Debugging}



The following debugging options are specific to the internal 
function of {\em zmsh}: 
\begin{description}
\item[{\tt -C}] \mbox{}

Print code generation output onto 
{\tt stdout}. If this option is doubled, the non-optimized 
code is printed out instead. 

\item[{\tt -I}] \mbox{}

Print runtime interpreter activity onto 
{\tt /dev/tty}. 

\item[{\tt -L}] \mbox{}

Print lexer output onto {\tt stdout}. 

\item[{\tt -O}] \mbox{}

Optimize the compiled script. If this 
option is doubled, the optimized code is also printed out. 

\item[{\tt -P}] \mbox{}

Print parser output (S/SL trace output) 
onto {\tt stdout}. 

\item[{\tt -R}] \mbox{}

Print I/O actions onto {\tt /dev/tty}. 

\item[{\tt -S}] \mbox{}

Print scanner output (token assembly) 
onto {\tt stdout}. 

\item[{\tt -Y}] \mbox{}

Open {\tt /dev/tty} for internal 
debugging use. 

\end{description}





\subsection{Security Issues}

Text to be inserted here.




\subsection{Internal Functions}

This section describes the router internal functions.

% -------------------------------------------
\hrule
\subsubsection{``:''}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt {\bf :}}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{``.'', ``include''}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt {\bf .} script}

\item[{\bf Return Values:}] \mbox{}

status

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{``['', ``test''}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt {\bf {[}} \{test parameters\} {\bf {]}}}

\item[{\bf Alternate syntax:}] \mbox{}

{\tt {\bf {test}} \{test parameters\}}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 1}] \mbox{}

True.

\item[{\tt 0}] \mbox{}

False.

\item[{\tt -1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{itemize}
\item File testing unary prefix functions:
\begin{description}
\item[{\tt -b file}] \mbox{}

True if file exists and is block special.

\item[{\tt -c file}] \mbox{}

True if file exists and is character special.

\item[{\tt -d file}] \mbox{}

True if file exists and is a directory.

\item[{\tt -f file}] \mbox{}

True if file exists and is a regular file.

\item[{\tt -g file}] \mbox{}

True if file exists and is set-group-id.

\item[{\tt -k file}] \mbox{}

True if file has its ``sticky'' bit set.

\item[{\tt -p file}] \mbox{}

True if file exists and is a named pipe.

\item[{\tt -r file}] \mbox{}

True if file exists and is readable.

\item[{\tt -s file}] \mbox{}

True if file exists and has a size greater than zero.

\item[{\tt -t {[fd]}}] \mbox{}

True if {\tt fd} is opened on a terminal. 
If {\tt fd} is omitted, it defaults to 1 (standard output).

\item[{\tt -u file}] \mbox{}

True if file exists and its set-user-id bit is set.

\item[{\tt -w file}] \mbox{}

True if file exists and is writable.

\item[{\tt -x file}] \mbox{}

True if file exists and is executable.

\end{description}

\item String testing binary functions:
\begin{description}
\item[{\tt str1 = str2}] \mbox{}

True if the strings are equal.

\item[{\tt str1 != str2}] \mbox{}

True if the strings are not equal.

\end{description}

\item Interget value testing binary functions:
\begin{description}
\item[{\tt iexpr -eq iexpr}] \mbox{}

True if values are equal.

\item[{\tt iexpr -ne iexpr}] \mbox{}

True if values are not equal.

\item[{\tt iexpr -gt iexpr}] \mbox{}

True if value1 is greater than value2.

\item[{\tt iexpr -ge iexpr}] \mbox{}

True if value1 is greater or equal than value2.

\item[{\tt iexpr -lt iexpr}] \mbox{}

True if value1 is less than value2.

\item[{\tt iexpr -le iexpr}] \mbox{}

True if value1 is less or equal than value2.

\end{description}

\item File comparison binary functions:
\begin{description}
\item[{\tt file1 -nt file2}] \mbox{}

True if file1's mtime is newer than file2's.

\item[{\tt file1 -ot file2}] \mbox{}

True if file1's mtime is older than file2's.

\item[{\tt file1 -ef file2}] \mbox{}

True if both files have same inode, and device.

\end{description}

\item Logical functions:
\begin{description}
\item[{\tt ! expr}] \mbox{}

Unary NOT

\item[{\tt expr -a expr}] \mbox{}

Binary AND

\item[{\tt expr -o expr}] \mbox{}

Binary OR

\item[{\tt ( expr )}] \mbox{}

Parenthesis

\end{description}
\end{itemize}




\item[{\bf Notes:}] \mbox{}

This is basically the shell {\tt {[}} a.k.a. 
{\tt test} program.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{attributes}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt attributes object-reference}

\item[{\bf Return Values:}] \mbox{}

The property list symbol (4th) component 
of an address quad.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{basename}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt basename pathname [ suffix ]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

If a suffix is given and matches the filename, 
the suffix too is stripped from the filename.

\item[{\bf Notes:}] \mbox{}

Prints the base filename of the pathname.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{break}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt break}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 1}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{builtin}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt builtin}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{builtins}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt builtins}

\item[{\bf Return Values:}] \mbox{}

none  

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

List builtin functions.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{car}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt car object-reference}

\item[{\bf Return Values:}] \mbox{}

Pointer to copied lisp-object of 
object-reference's {\tt car} operation.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This command is synonymous to the {\tt channel} 
and {\tt first} commands.  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{cd}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt cd [directory]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}

{\tt cd} successful.

\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{cdr}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt cdr object-reference}

\item[{\bf Return Values:}] \mbox{}

Pointer to copied lisp-object of 
object-reference's {\tt cdr} operation.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This command is synonymous to the {\tt rest}
command.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{channel}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt channel object-reference}

\item[{\bf Return Values:}] \mbox{}

The channel (1st) component of an address
quad.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

The {\tt car} and {\tt first} commands are 
synonymous to this command. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{continue}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt continue}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 1}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{daemon}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt daemon}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Starts the {\em router} running in daemon mode, 
scanning the {\tt \$POSTOFFICE/router/} directory every few 
seconds for message files to process. This function is invoked 
automatically by other code in the {\em router} program and has no 
other purpose.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{db}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt db \{add\verb/|/flush\verb/|/owner\verb/|/print\verb/|/remove\verb/|/toc\} {[database [key [value]]]}}



\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt {a[dd]}}] \mbox{}

Add a {\tt key,value} 
entry to the database, if possible.

\item[{\tt {f[lush]}}] \mbox{}

Remove all entries from the database, 
if possible.

\item[{\tt {o[wner]}}] \mbox{}

Print the account name of the owner 
of the database, if possible. This is usually determined by the 
files associated with the database.

\item[{\tt {p[rint]}}] \mbox{}

Print all entries of the database, 
if possible. 

\item[{\tt {r[emove]}}] \mbox{}

Remove a {\tt key} entry 
from the database, if possible.

\item[{\tt {t[oc]}}] \mbox{}

Print a table of defined relations 
and their associated information. This table has five columns, 
in order: the name of the relation, its type and subtype, cache 
entries and maximum size, flags, and associated files. See the 
{\tt relation} function for more information.

\end{description}


\item[{\bf Notes:}] \mbox{}

\begin{alltt}
DBType    add flush owner print remove
------    ----------------------------
incore    yes yes   yes   yes   yes
header    yes yes   yes   yes   yes
ordered   no  yes   yes   yes   no
unordered yes yes   yes   yes   yes
hostsfile no  no    no    yes   no
bind      no  no    no    no    no
ndbm      yes yes   yes   yes   yes
gdbm      yes yes   yes   yes   yes
dbm       yes yes   yes   yes   yes
yp        no  no    yes   yes   no
btree     yes yes   yes   yes   yes
ldap      no  no    yes   no    no
\end{alltt}


\end{description}


% -------------------------------------------
\hrule
\subsubsection{dblookup}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt dblookup key}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt cell}] \mbox{}



\item[{\tt NULL}] \mbox{}

Error.  

\end{description}


\item[{\bf Options:}] \mbox{}

none

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{echo}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt echo [string-expressions]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}

        

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -n}] \mbox{}

Don't print newline at end of string.

\end{description}


\item[{\bf Notes:}] \mbox{}

The access function to the database facilities in the 
{\em router}.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{elements}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt elements lisp-object}

\item[{\bf Return Values:}] \mbox{}

{\tt lisp-object}

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{envars}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt envars}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Print internal variable tree.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{erraddron}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt erraddron [file]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Specifies a filename to append all address 
parsing error messages to. If there is no argument given, the 
logging is stopped. This is primarily for curious postmasters 
or other collectors of address trivia.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{eval}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt eval expression}

\item[{\bf Return Values:}] \mbox{}

status

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{exit}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt exit}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:} ] \mbox{}

Exit from the shell with exit code.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{export}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt export [variable-name ...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Exports variable name(s). If no variables are given, 
export prints a list of which variables have been exported.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{filepriv}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt filepriv file [uid]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none

\item[{\bf Notes:}] \mbox{}

Prints the numeric user id of the least 
privileged account that can modify the specified file. This is 
determined by an approximation that pessimistically assumes that 
any file or directory writable by group or others is insecure, 
and optimistically assumes that it is enough to check a file and 
its parent directory instead of all the way to the filesystem root. 
The reason for the latter is that if grandparent directories are 
insecure, the system is likely to have just as bad potential 
problems as can be created by using mail to run processes with
forged powers (besides, doing the full check would be quite expensive).

If a second argument is given, it is the numeric user id to assume 
for the file. This means only the parent directory will be checked 
for nonwritability and for having the same (or a 0) uid.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{first}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt first object-reference}

\item[{\bf Return Values:}] \mbox{}

Pointer to copied lisp-object of 
object-reference's {\tt car} operation.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This command is synonymous to the {\tt car} 
and {\tt channel} commands.  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{gensym}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt gensym}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Generates and prints a new symbol name in the 
sequence {\tt g0} to {\tt gN} every time it is called. The 
sequence is reset and any symbol values destroyed after the {\em router} 
has processed a message. This function is used to generate new symbols, to 
hold attached address property lists, during alias expansion.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{get}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt get property-list key}

\item[{\bf Return Values:}] \mbox{}

{\tt property-list}

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Returns a property list corresponding to key string.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{getopts}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt getopts optstring-name [arguments ...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{grind}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt grind lisp-object}

\item[{\bf Return Values:}] \mbox{}

Pointer to list of {\tt varcell}.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{groupmembers}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt groupmembers groupname}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Prints the accounts that are listed as 
members of a group in the system groups file, one per line.
Note that accounts with the same login group id, but that are 
not listed in the groups file, will not appear in this list.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{hash}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt hash [-r] [command names]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -r}] \mbox{}

Path is flushed.

\end{description}


\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{homedirectory}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt homedirectory user}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Prints the home directory of the specified 
user account.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{host}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt host object-reference}

\item[{\bf Return Values:}] \mbox{}

The host (2nd) component of an 
address quad.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{hostname}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt hostname [name]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Sets the {\em router}'s idea of the
system hostname. Without an argument the name is retrieved from
the system and printed. The {\em router} has no preconceived 
notion of what the hostname is, so Message-Id and Received headers 
will only be generated if a hostname has been set using this function.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{lappend; \em experimental}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt lappend varname anyvalue}

\item[{\bf Return Values:}] \mbox{}

none

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This appends content of list object ({\em anyvalue}) to named
{\em varname} variable.

This function has been created to manage problems associated
at the use of ``{\em setf}'', which in current implementation
causes $O(n^{2})$ kind memory consumption by creating a new
temporary copy of the target list into the heap for all invocations
of ``{\em setf}''.  Result being that for a large list the system
will quickly use massive amounts of heap.

\end{description}

% -------------------------------------------
\hrule
\subsubsection{last}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt last lisp-object}

\item[{\bf Return Values:}] \mbox{}

Return a pointer to last cell of 
{\tt varcell}'s list.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{length}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt length lisp-object}

\item[{\bf Return Values:}] \mbox{}

String of length of {\tt varcell}'s 
parameter list.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{list}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt list lisp-object}

\item[{\bf Return Values:}] \mbox{}

{\tt lisp-object}

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{listaddresses}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt listaddresses [-e error-address] [-E errors-to-address] [-c comment]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -e}] \mbox{}

Any syntax errors at list parsing will cause a 
report to be mailed to the given address.

\item[{\tt -E}] \mbox{}

If an error occurs while messages are being delivered, 
the `errors-to-address' can be used to force error message destination 
elsewhere than to the default `sender' of the message.

\item[{\tt -c}] \mbox{}

A comment will be inserted in the error report.

\end{description}


\item[{\bf Notes:}] \mbox{}

Filters an RFC822 address list on standard input 
to produce one normal form (no non-address tokens) address per line on 
its output. This function can be used to parse the alias file or .forward 
files or similar.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{listexpand}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt listexpand [-c comment] [-e error-address] [-E errors-to-address] \$attribute \$localpart \$origaddr {\(<\)} listfile}

\item[{\bf Return Values:}] \mbox{}

{\tt lisp-object}

\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -e error-address}] \mbox{}

Any syntax errors at list 
parsing will cause a report to be mailed to the given address.

\item[{\tt -E errors-to-address}] \mbox{}

If an error occurs while messages 
are being delivered, the `errors-to-address' can be used to force error 
message destination elsewhere than to the default `sender' of the message.

\item[{\tt -c comment}] \mbox{}

A comment will be inserted in the error report.

\end{description}


\item[{\bf Notes:}] \mbox{}

Implements the most common pipeline where 
{\tt listaddresses} was used with more efficient memory consumption 
handling. (That is, without variable duplicating {\tt setf}'s.)

\end{description}


% -------------------------------------------
\hrule
\subsubsection{login2uid}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt login2uid username}

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Notes:}] \mbox{}

Prints the uid associated with the specified
account name, if any. A side-effect is to add the GECOS name field of 
the account to the {\tt fullname} in-core database, to add the login 
name to uid mapping to the {\tt pwnam} in-core database, and to add 
the uid to login name mapping to the {\tt pwuid} in-core database.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{lreplace; \em experimental}

\begin{description}
\item[{\bf Syntax1:}] \mbox{}

{\tt lreplace varname indexnum anyvalue}

\item[{\bf Syntax2:}] \mbox{}

{\tt lreplace varname fieldname anyvalue}

\item[{\bf Return Values:}] \mbox{}

none

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This replaces designated field on {\em varname} variable containing
list-like data with {\em anyvalue} value.

The field designation can be given in numeric form, where
the field index can be numeric (first field is zero), or
{\em keyname} on key/value pair list.

If a key is not found (with key/value pairs), then designated pair
is added to the list.

\begin{alltt}
tt=(aa 11 bb 22 cc 33 dd 44)
lreplace tt aa zz
grind $tt
(zz 11 bb 22 cc 33 dd 44)
lreplace tt 0 aaa
grind $tt
(aaa 11 bb 22 cc 33 dd 44)
lreplace tt zz aa
grind $tt
(aaa 11 bb 22 cc 33 dd 44 zz aa)
\end{alltt}

This function has been created to manage problems associated
at the use of ``{\em setf}'', which in current implementation
causes $O(n^{2})$ kind memory consumption by creating a new
temporary copy of the target list into the heap for all invocations
of ``{\em setf}''.  Result being that for a large list the system
will quickly use massive amounts of heap.

\end{description}

% -------------------------------------------
\hrule
\subsubsection{malcontents}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt malcontents}

\item[{\bf Return Values:}] \mbox{}

none  

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{printaliases}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt printaliases [-v] [-o indexoutputfile] file}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -v}] \mbox{}

Verbose.

\item[{\tt -o indexoutputfile}] \mbox{}

Each header line will also generate 
a {\tt header TAB byteoffset} line in the indexfile.

\item[{\bf Notes:}] \mbox{}

Reads RFC822 syntax header lines from the specified
file, parses them assuming contents must be an address list, and sorts 
and prints the header lines with all addresses in normal form. Comments 
are allowed; they extend from the character `\#' at the beginning of 
a line, or after an address, to the end of line. This function is used 
by the {\em newaliases(1)} program to generate the aliases database 
from a source file.

\end{description}


\end{description}


% -------------------------------------------
\hrule
\subsubsection{process}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt process messagefile}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

The protocol switch function. It is called by
the {\tt daemon} function to process a message found in the 
{\tt \$POSTOFFICE/router/} directory. This function will 
in turn call an internal protocol-specific function which knows the 
syntax and semantics of the message file. The current version knows 
about messages submitted using the {\tt MSG\_RFC822} parameter to 
{\tt mail\_open(3)}. For that case, the protocol function is called 
{\tt rfc822}. {\em router} has a bit more complex directory 
semantics, than is stated above. See {\tt zmailer(3)} for details. 
Although the {\tt process} function is provided built in, it is 
usually overridden by a defined function in the {\em router} 
configuration file.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{read}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt read [variable]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}

Successful read.

\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{recase}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt recase [-u \verb/|/ -l \verb/|/ -p] string}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -u}] \mbox{}

Convert into uppercase.

\item[{\tt -l}] \mbox{}

Convert into lowercase.

\item[{\tt -p}] \mbox{}

Prettify.

\end{description}


\item[{\bf Notes:}] \mbox{}

A case-mapping function that prints the parameter 
string in either all-uppercase, all-lowercase, or capitalized (pretty).

\end{description}


% -------------------------------------------
\hrule
\subsubsection{recipient}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt recipient}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 1}] \mbox{}

Is a recipient address.

\item[{\tt 0}] \mbox{}

Is not.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

A boolean function that returns the value of 
the statement ``executing a header rewriting function and the address 
is a recipient address in a message header''.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{relation}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt relation -t {dbtype[,subtype] [-f file -e\# -s\# -bilmnu -d driver]} name}

Options are listed below. {\tt name} is the name of the relation
that is wanted to be created. Examples:
\begin{alltt}
relation -t bind,mx mxhost
relation -t ordered -f $MAILVAR/db/routes routes
relation -t ordered -b -f /usr/lib/news/active.sorted newsgroups
\end{alltt}




\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1..7}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -t {dbtype[,subtype]}}] \mbox{}

One of the known types 
of databases, currently: 
\begin{description}
\item[{\tt incore}] \mbox{}

A database maintained in virtual memeory (using 
splay trees). This type should not be used for any database that must 
periodically be flushed, since all occupied memory can be freed.

\item[{\tt header}] \mbox{}

A database type used to store RFC822 header 
semantics information. It is unlikely to be used for anything else.

\item[{\tt ordered}] \mbox{}

A file with key-value pairs on every line, 
separated by whitespace, sorted by key. 

\item[{\tt unordered}] \mbox{}

A file with key-value pairs on every line, 
separated by whitespace. 

\item[{\tt hostsfile}] \mbox{}

{\em hosts(5)} file.

\item[{\tt bind}] \mbox{}

The BIND implementation of a Domain Name System 
resolver. The subtype for this type is the name of a Resource Record 
type in the {\tt IN} class.

\item[{\tt ndbm}] \mbox{}

The new DBM library. The BSD4.4 has a thing called 
{\tt db}, which is a different thing, but it can be used in place 
of {\tt ndbm} via its interface library. (The {\tt BSD4.4-db} 
does have only one database file, not two, like {\tt ndbm} does.)

\item[{\tt gdbm}] \mbox{}

The GNU implementation of the new DBM library. 
{\bf Note:} GDBM uses one file, which is named exactly as you 
parametrize it. This is unlike NDBM, which appends .dir and .pag to 
the supplied name!

\item[{\tt dbm }] \mbox{}

The old DBM library. There can be only one DBM 
open at the time, and this system keeps them all open all the time. 
Avoid if you can.

\item[{\tt yp}] \mbox{}

The Network Information Service from Sun Microsystems 
Inc. (Later renamed to be NIS, the still newer NIS+ is not supported).

\item[{\tt btree}] \mbox{}

\end{description}


\item[{\tt -f file}] \mbox{}

A file associated with the database, typically 
the file containing the data, or the basename of DBM files or something 
similarly relevant to the database access routine. 

\item[{\tt -e\#}] \mbox{}

The default time-to-live on cached information. 
When the information has been in the cache for this many seconds, it 
is discarded. The default is 0. 

\item[{\tt -s\#}] \mbox{}

Sets the cache size to the specified number. 
The default is usually 10, depending on the database type. 

\item[{\tt -b}] \mbox{}

If the key exists in the database, return the key 
as the value. 

\item[{\tt -i}] \mbox{}

If the key exists, its value is a byte offset into 
a file named by the subtype for this database. The value then becomes 
the concatenation of the data on the lines following that offset which 
start with whitespace. This is used for the aliases file. 

\item[{\tt -l}] \mbox{}

Map all keys to lowercase before searching.

\item[{\tt -m}] \mbox{}

Check for file content modification before every 
access. Reopen the file when a change is detected. This option is 
used when the {\em router} should discover changes to a database
underfoot so it need not be restarted to use new data. This is 
recommended on relations which use unordered, or ordered datasets 
(aliases, routes, ...), and especially if the system is configured 
to use {\tt mmap(2)} facility. Updating such databases should 
preferably use {\tt mv} command to move a new version of the 
database in place of the old one. 

\item[{\tt -n}] \mbox{}

If the key exists in the database and the value is 
null or list, return the key as value. Otherwise return the value 
retrieved, if any. 

\item[{\tt -u}] \mbox{}

Map all keys to uppercase before searching. 

\item[{\tt -d driver}] \mbox{}

Specifies a search driver that allows
searching for structured keys using special knowledge. The 
argument to this option must be a known driver. Currently the 
only known driver is {\tt pathalias} which will search a
pathalias format database for an entry matching a domain name 
using the pathalias rules.

\end{description}


\item[{\bf Notes:}] \mbox{}

On systems with {\tt USE\_MMAP} the ordered 
and unordered databases are r/o mapped into memory, and for ordered 
case, a special line-index is generated for speeding up the binary 
search. (Makes less system calls that way.)

\end{description}


% -------------------------------------------
\hrule
\subsubsection{rest}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt rest object-reference}

\item[{\bf Return Values:}] \mbox{}

Pointer to copied lisp-object of 
object-reference's {\tt cdr} operation.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This command is synonymous to the {\tt cdr}
command.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{return}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt return lisp-object}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt lisp-object}] \mbox{}

String contains a not ASCII digit character.    
(Returns a pointer to {\tt varcell}'s string.)

\item[{\tt statusp}] \mbox{}

ASCII digit character. (Returns numeric value.)

\item[{\tt NULL}] \mbox{}

Invalid lisp-object.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{returns}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt returns lisp-object}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt string}] \mbox{}



\item[{\tt lisp-object}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{rfc822}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt rfc822 messagefile}

\item[{\bf Return Values:}] \mbox{}

{\tt status}

\item[{\bf Options:}] \mbox{}

none

\item[{\bf Notes:}] \mbox{}

This function controls the parsing and 
processing of the message file in RFC822/976 format. It is 
called by the {\tt process} function. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{rfc822date}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt rfc822date}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none

\item[{\bf Notes:}] \mbox{}

Prints the current time in RFC822 format. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{rfc822syntax}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt rfc822syntax address}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

This is a simple interface to the address 
parser. If the command line argument is a syntactically valid 
RFC822 address, this command is silent and returns 0 as exit 
status. If there is a parse error, a verbose error message is 
printed to {\tt stdout} and the function returns a non-0 
exit status. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{runas}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt runas user function [arguments...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Changes the current effective user id 
of the {\em router} process to that given (which may be 
numeric or an account name), then runs the specified function 
with the specified arguments, then switches the effective 
user id of the process back (to root). 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{sender}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt sender}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 1}] \mbox{}

Is a sender address.

\item[{\tt 0}] \mbox{}

Is not.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

A boolean function that returns the value of 
the statement ``executing a header rewriting function and the address 
is a sender address in a message header''. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{set}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt set [-a -e -f -h -n -t -u -v -x -L -C -P -S -k -] variable}

Without parameters {\tt set} prints variable values.



\item[{\bf Return Values:}] \mbox{}

Pointer to copied structure of {\tt car} 
operation.

\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -a}] \mbox{}

Automatically export changed variables.

\item[{\tt -e}] \mbox{}

Exit on error exit status of any command.

\item[{\tt -f}] \mbox{}

Disable filename generation (no globbing).

\item[{\tt -h}] \mbox{}

Hash program locations.

\item[{\tt -n}] \mbox{}

Read commands but do not execute them.

\item[{\tt -t}] \mbox{}

Read and execute one command only.

\item[{\tt -u}] \mbox{}

Unset variables are error on substitution.

\item[{\tt -v}] \mbox{}

Print shell input lines as they are read.

\item[{\tt -x}] \mbox{}

Print commands as they are executed.

\item[{\tt -L}] \mbox{}

Trace LEXER processing (sslWalker).

\item[{\tt -C}] \mbox{}

Print branch and emit inputs (sslWalker).

\item[{\tt -P}] \mbox{}

Trace execution (sslWalker).

\item[{\tt -S}] \mbox{}

Print input buffers when used (sslWalker). 

\item[{\tt -k}] \mbox{}

Not supported option.

\item[{\tt -}] \mbox{}

Do nothing.

\end{description}


\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{setf}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt setf variable-reference [new-value]}

\item[{\bf Return Values:}] \mbox{}

Pointer to original variable reference.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Replaces variable reference within a {\tt varcell}.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{shift}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt shift [number]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Modifies caller's argument vector.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{sleep}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt sleep number}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{squirrel}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt squirrel [-]event}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt -}] \mbox{}

Set flag value to 0.

\item[{\tt {\(<\)}none>}] \mbox{}

Set flag value to 1. 

The events are: 
\begin{itemize}
\item {\tt breakin}
\item {\tt badheader}
\item {\tt illheader}
\item {\tt nochannel}
\item {\tt nosender}
\end{itemize}


\end{description}


\item[{\bf Notes:}] \mbox{}

Sets the kinds of events that cause a message 
to be copied into the {\tt \$POSTOFFICE/postman/} directory. 
Whether or not a `{\tt -}' is necessary for an event depends on 
the current state of the event's flag. The usage message will 
indicate what to do to toggle the event flag. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{stability}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt stability [on \verb/|/ off]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Determines whether the {\em router} will 
process incoming messages in arrival order (when on), or in random 
order determined by position in the router directory. The {\em router} 
will by default do the first queue scan in stable mode, and subsequent 
scans in unstable mode. The name of this command is the name for a 
similar characteristic of sorting algorithms. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{``test'', ``[''}

{\em see: ``['', ``test''}

% -------------------------------------------
\hrule
\subsubsection{times}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt times }

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{trace}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt trace key1 ... keyN}

Enables tracing of the specified items. The valid keywords 
are listed in the options below. 

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

\begin{description}
\item[{\tt all}] \mbox{}

Turns on all tracing options. You only 
do this to test the I/O capabilities of your system. 

\item[{\tt assign}] \mbox{}

Prints shell variable assignments. 

\item[{\tt bind}] \mbox{}

Prints various information from the 
code that calls the DNS resolver. 

\item[{\tt compare}] \mbox{}

Prints {\tt sift} statement 
pattern-selector comparisons. 

\item[{\tt db}] \mbox{}

Prints database lookups, including cache 
search and update information. 

\item[{\tt final}] \mbox{}

Prints the message envelope information 
after processing each message. 

\item[{\tt functions}] \mbox{}

Prints shell function calls and 
return values, with nesting indicated by indentation. 

\item[{\tt matched}] \mbox{}

Prints {\tt sift} statement 
pattern-selector matches. 

\item[{\tt on}] \mbox{}

Same as {\tt functions}. 

\item[{\tt regexp}] \mbox{}

Prints regular expression matching execution. 

\item[{\tt resolv}] \mbox{}

Turns on the {\tt RES\_DEBUG} flag in the 
{\tt BIND} resolver library, and prints various information 
from the code that calls the DNS resolver. 

\item[{\tt rewrite}] \mbox{}

Prints the tokenized addresses sent through 
the message header address rewriting functions. 

\item[{\tt router}] \mbox{}

Prints the tokenized addresses sent through 
the {\tt router} function. 

\item[{\tt sequencer}] \mbox{}

Prints the procedural steps taken during 
message processing. 

\item[{\tt memory}] \mbox{}

Prints memory allocation information after 
each message. 

\end{description}


\item[{\bf Notes:}] \mbox{}

 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{trap}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt trap [[script trap\_nro] ...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

If no parameters are given, {\tt trap} prints all 
known traps.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{type}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt type [command ...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}


% -------------------------------------------
\hrule
\subsubsection{uid2login}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt uid2login uid}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Prints the first account name associated with 
a specified user id, if any, or {\tt uid\#uid} if no account 
exists with that user id. It has the same side-effects as the 
{\tt login2uid} function. 

\end{description}


% -------------------------------------------
\hrule
\subsubsection{umask}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt umask [octal-number-mask]}

\item[{\bf Return Values:}] \mbox{}

Pointer to copied structure of {\tt car} 
operation.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

Without parameters default mask is 077.

\end{description}


% -------------------------------------------
\hrule
\subsubsection{unset}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt unset [variable ...]}

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{untrace}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt untrace key1 ... keyN}

Disables tracing of the specified items. 

\item[{\bf Return Values:}] \mbox{}

\begin{description}
\item[{\tt 0}] \mbox{}



\item[{\tt 1}] \mbox{}

Error.

\end{description}


\item[{\bf Options:}] \mbox{}

See the {\tt trace} function for 
valid keywords. 

\item[{\bf Notes:}] \mbox{}

  

\end{description}


% -------------------------------------------
\hrule
\subsubsection{user}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt user object-reference}

\item[{\bf Return Values:}] \mbox{}

The next-address (3rd) component of 
and address quad.

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}

% -------------------------------------------
\hrule
\subsubsection{wait}

\begin{description}
\item[{\bf Syntax:}] \mbox{}

{\tt wait [pid]}

\item[{\bf Return Values:}] \mbox{}

{\tt retcode}

\item[{\bf Options:}] \mbox{}

none  

\item[{\bf Notes:}] \mbox{}

none

\end{description}

