Router

ZMailer: The Manual; v1.99.20
Prev |  | Next

# Chapter 21. Router

The 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 `$`POSTOFFICE`/router/` directory. The 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 `$`POSTOFFICE`/scheduler/` and `$`POSTOFFICE`/transport/` directories for use by the scheduler in the next step of message processing. The original message file is then moved to the `$`POSTOFFICE`/queue/` directory.

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

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 zmailer(1) script, as in ``zmailer router''. This will start the router as a daemon and kill the previous incarnation of the router.

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

Parameters:

-d

  Detach and run as a daemon.

-f configfile

  Overrides the default configuration file `$`MAILSHARE`/router.cf`.

-i

  Run interactively, presenting a zmsh session with the configuration file preloaded.

-k

  Kill the currently running router by sending it a `SIGTERM` signal.

-L logfile

  Overrides the default log file location `$`LOGDIR`/router`.

-n #routers

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

-o zmshoptions

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

-P postoffice

  Specifies an alternate `$`POSTOFFICE`/` directory.

-S

  Can be used to turn off non-serious syslogging.

-s

  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.

-t traceflag

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

-V

  Print version message and run interactively.

To restart a router daemon:

       router -dk

To test an address, start up an interactive session:

      router -i

or if the ZMailer sendmail(8) is installed:

      sendmail -bt

Then just use the pre-defined functions.

# 21.1. ZMSH Script Language

zmsh is an implementation of the Bourne shell suitable for use with the ZMailer 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 in-core for future reference. If the input is an included file, the shell will try to save the byte-code form in a `.fc` file associated with the input file. For example, if input is from `file.cf`, the shell will try to create `fc/file.fc` and then `file.fc`. These files will in turn be searched for and loaded (after a consistency check) whenever a `.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.

Usage:

      zmsh [ -CILOPRSYaefhinstuvx ] [ -c command ] [ script ...]

Parameters:

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

  `-c command`

    Run the given argument as a shell command script.

  `-a`

    Automatically export new or changed shell variables.

  `-e`

    Exit on non-zero status return of any command.

  `-f`

    Disables filename generation.

  `-h`

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

  `-i`

    This shell is interactive, meaning prompts are printed when ready for more input, `SIGTERM` signal is ignored, and the shell does not exit easily. This flag is automatically set if `STDIN` and `STDERR` are both attached to a `/dev/tty`.

  `-n`

    Read commands but do not execute them.

  `-s`

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

  `-t`

    Exit after running one command.

  `-u`

    Unset variables produce an error on substitution.

  `-v`

    Print shell input as it is read.

  `-x`

    Print commands as they are executed.

# 21.2. Configuration Script Writing Rules

    Text to be inserted here.

# 21.3. Debugging

The following debugging options are specific to the internal function of zmsh:

-C

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

-I

  Print runtime interpreter activity onto `/dev/tty`.

-L

  Print lexer output onto `stdout`.

-O

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

-P

  Print parser output (S/SL trace output) onto `stdout`.

-R

  Print I/O actions onto `/dev/tty`.

-S

  Print scanner output (token assembly) onto `stdout`.

-Y

  Open `/dev/tty` for internal debugging use.

# 21.4. Security Issues

    Text to be inserted here.

# 21.5. Script Language Internal Functions

This section describes the router internal functions.

## 21.5.1. ``:'' (doublecolon)

Syntax:

       : <SPC> anything else forming a command pipeline

Description:

  none

Return Values:

  0

Options:

  none

Notes:

  none

## 21.5.2. ``.'', ``include''

Syntax:

       . scriptfilename

Return Values:

  status

Options:

  none

Notes:

  none

## 21.5.3. ``['', ``test''

Syntax:

      [ {test parameters} ]

Alternate syntax:

      test {test parameters}

Return Values:

  1

    True.

  0

    False.

  -1

    Error.

Options:

  - File testing unary prefix functions:

    `-b file`

      True if file exists and is block special.

    `-c file`

      True if file exists and is character special.

    `-d file`

      True if file exists and is a directory.

    `-f file`

      True if file exists and is a regular file.

    `-g file`

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

    `-k file`

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

    `-p file`

      True if file exists and is a named pipe.

    `-r file`

      True if file exists and is readable.

    `-s file`

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

    `-t {[fd]}`

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

    `-u file`

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

    `-w file`

      True if file exists and is writable.

    `-x file`

      True if file exists and is executable.

  - String testing binary functions:

    `str1 = str2`

      True if the strings are equal.

    `str1 != str2`

      True if the strings are not equal.

  - Interget value testing binary functions:

    `iexpr -eq iexpr`

      True if values are equal.

    `iexpr -ne iexpr`

      True if values are not equal.

    `iexpr -gt iexpr`

      True if value1 is greater than value2.

    `iexpr -ge iexpr`

      True if value1 is greater or equal than value2.

    `iexpr -lt iexpr`

      True if value1 is less than value2.

    `iexpr -le iexpr`

      True if value1 is less or equal than value2.

  - File comparison binary functions:

    `file1 -nt file2`

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

    `file1 -ot file2`

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

    `file1 -ef file2`

      True if both files have same inode, and device.

  - Logical functions:

    `! expr`

      Unary NOT

    `expr -a expr`

      Binary AND

    `expr -o expr`

      Binary OR

    `( expr )`

      Parenthesis

Notes:

  This is basically the shell ```[`'' a.k.a. ```test`'' program.

## 21.5.4. attributes

Syntax:

        attributes object-reference

Return Values:

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

Options:

  none

Notes:

  none

## 21.5.5. basename

Syntax:

      basename pathname [ suffix ]

Return Values:

  0

    ok, result string to `STDOUT`.

  1

    Error.

Options:

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

Notes:

  Prints the base filename of the pathname.

## 21.5.6. break

Syntax:

      while ...
      do
         ...
         break
         ...
      done

      case ...
         ...
         break
         ...
      esac

Return Values:

  1

Options:

  none

Notes:

  none

## 21.5.7. builtin

Syntax:

  NOT IMPLEMENTED!

      builtin {builtin command name, and its params}

Return Values:

  0

Options:

  none

Notes:

  NOT IMPLEMENTED!

  Ensures that named command is builtin within the scheduler, and not a) external, b) script based.

## 21.5.8. car

Syntax:

      car object-reference

Return Values:

  Pointer to copied lisp-object of object-reference's `car` operation.

Options:

  none

Notes:

  This command is synonymous to the `channel` and `first` functions.

## 21.5.9. cd

Syntax:

      cd [directory]

Return Values:

  0

    `cd` successful.

  1

    Error.

Options:

  none

Notes:

  none

## 21.5.10. cdr

Syntax:

      cdr object-reference

Return Values:

  Pointer to copied lisp-object of object-reference's `cdr` operation.

Options:

  none

Notes:

  This command is synonymous to the `rest` function.

## 21.5.11. channel

Syntax:

      channel object-reference

Return Values:

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

Options:

  none

Notes:

  The `car` and `first` functions are synonymous to this one.

## 21.5.12. continue

Syntax:

       continue

Return Values:

  1

Options:

  none

Notes:

  none

## 21.5.13. daemon

Syntax:

      daemon

Return Values:

  0

Options:

  none

Notes:

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

## 21.5.14. db

Syntax:

  db {add} {`database`} {`key`} {`value`}

  db {flush} {`database`}

  db {owner} {`database`}

  db {print} {`database`}

  db {remove} {`database`} {`key`}

  db {toc}

Return Values:

  0

  1

    Error.

Options:

  `a[dd]`

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

  `f[lush]`

    Remove all entries from the database, if possible.

  `o[wner]`

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

  `p[rint]`

    Print all entries of the database, if possible.

  `r[emove]`

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

  `t[oc]`

    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 `relation` function for more information.

Notes:

      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
      bhash     yes yes   yes   yes   yes
      btree     yes yes   yes   yes   yes
      ldap      no  no    yes   no    no

## 21.5.15. dblookup

Syntax:

  Does lookup via `relation` defined dblookup vector:

      dblookup key

Return Values:

  cell

    Lookup result

  `NULL`

    Error.

Options:

  none

Notes:

  The access function to the database facilities in the router.

## 21.5.16. echo

Syntax:

      echo [-n] [string-expressions]

Return Values:

  0

Options:

  `-n`

    Don't print newline at end of string.

Notes:

  none

## 21.5.17. elements

Syntax:

      elements lisp-object

Return Values:

  lisp-object

Options:

  none

Notes:

  none

## 21.5.18. envars

Syntax:

      envars

Return Values:

  0

Options:

  none

Notes:

  Print internal variable tree.

## 21.5.19. erraddron

Syntax:

      erraddron [file]

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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.

## 21.5.20. eval

Syntax:

  {\tt eval expression}

Return Values:

  status

Options:

  none

Notes:

  none

## 21.5.21. exit

Syntax:

  {\tt exit}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  Exit from the shell with exit code.

## 21.5.22. export

Syntax:

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

Return Values:

  {\tt 0}

Options:

  none

Notes:

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

## 21.5.23. filepriv

Syntax:

  {\tt filepriv file [uid]}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  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.

## 21.5.24. first

Syntax:

  {\tt first object-reference}

Return Values:

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

Options:

  none

Notes:

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

## 21.5.25. gensym

Syntax:

  {\tt gensym}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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.

## 21.5.26. get

Syntax:

  {\tt get property-list key}

Return Values:

  {\tt property-list}

Options:

  none

Notes:

  Returns a property list corresponding to key string.

## 21.5.27. getopts

Syntax:

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

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  none

## 21.5.28. grind

Syntax:

  {\tt grind lisp-object}

Return Values:

  Pointer to list of {\tt varcell}.

Options:

  none

Notes:

  none

## 21.5.29. groupmembers

Syntax:

  {\tt groupmembers groupname}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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.

## 21.5.30. hash

Syntax:

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

Return Values:

  {\tt 0}

Options:

  {\tt -r}

    Path is flushed.

Notes:

  none

## 21.5.31. homedirectory

Syntax:

  {\tt homedirectory user}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  Prints the home directory of the specified user account.

## 21.5.32. host

Syntax:

  {\tt host object-reference}

Return Values:

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

Options:

  none

Notes:

  none

## 21.5.33. hostname

Syntax:

  {\tt hostname [name]}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  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.

## 21.5.34. lappend; \em experimental

Syntax:

  {\tt lappend varname anyvalue}

Return Values:

  none

Options:

  none

Notes:

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

## 21.5.35. last

Syntax:

  {\tt last lisp-object}

Return Values:

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

Options:

  none

Notes:

  none

## 21.5.36. length

Syntax:

  {\tt length lisp-object}

Return Values:

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

Options:

  none

Notes:

  none

## 21.5.37. list

Syntax:

  {\tt list lisp-object}

Return Values:

  {\tt lisp-object}

Options:

  none

Notes:

  none

## 21.5.38. listaddresses

Syntax:

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

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  {\tt -e}

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

  {\tt -E}

    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.

  {\tt -c}

    A comment will be inserted in the error report.

Notes:

  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.

## 21.5.39. listexpand

Syntax:

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

Return Values:

  {\tt lisp-object}

Options:

  {\tt -e error-address}

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

  {\tt -E errors-to-address}

    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.

  {\tt -c comment}

    A comment will be inserted in the error report.

Notes:

  Implements the most common pipeline where {\tt listaddresses} was used with more efficient memory consumption handling.

## 21.5.40. login2uid

Syntax:

  {\tt login2uid username}

Options:

  none

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Notes:

  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.

## 21.5.41. lreplace; \em experimental

{\bf Syntax1:}

  {\tt lreplace varname indexnum anyvalue}

{\bf Syntax2:}

  {\tt lreplace varname fieldname anyvalue}

Return Values:

  none

Options:

  none

Notes:

  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.

        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)

## 21.5.42. malcontents

Syntax:

  {\tt malcontents}

Return Values:

  none

Options:

  none

Notes:

  none

## 21.5.43. printaliases

Syntax:

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

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  {\tt -v}

    Verbose.

  {\tt -o indexoutputfile}

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

  Notes:

    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.

## 21.5.44. process

Syntax:

  {\tt process messagefile}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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.

## 21.5.45. read

Syntax:

  {\tt read [variable]}

Return Values:

  {\tt 0}

    Successful read.

  {\tt 1}

    Error.

Options:

  none

Notes:

  none

## 21.5.46. recase

Syntax:

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

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  {\tt -u}

    Convert into uppercase.

  {\tt -l}

    Convert into lowercase.

  {\tt -p}

    Prettify.

Notes:

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

## 21.5.47. recipient

Syntax:

  {\tt recipient}

Return Values:

  {\tt 1}

    Is a recipient address.

  {\tt 0}

    Is not.

Options:

  none

Notes:

  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''.

## 21.5.48. relation

Syntax:

  {\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}

Return Values:

  {\tt 0}

  {\tt 1..7}

    Error.

Options:

  {\tt -t {dbtype[,subtype]}}

    One of the known types of databases, currently:

    {\tt incore}

      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.

    {\tt header}

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

    {\tt ordered}

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

    {\tt unordered}

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

    {\tt hostsfile}

      {\em hosts(5)} file.

    {\tt bind}

      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.

    {\tt ndbm}

      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.)

    {\tt gdbm}

      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!

    {\tt dbm }

      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.

    {\tt yp}

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

    {\tt btree}

  {\tt -f file}

    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.

  {\tt -e\#}

    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.

  {\tt -s\#}

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

  {\tt -b}

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

  {\tt -i}

    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.

  {\tt -l}

    Map all keys to lowercase before searching.

  {\tt -m}

    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.

  {\tt -n}

    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.

  {\tt -u}

    Map all keys to uppercase before searching.

  {\tt -d driver}

    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.

Notes:

  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.)

## 21.5.49. rest

Syntax:

  {\tt rest object-reference}

Return Values:

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

Options:

  none

Notes:

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

## 21.5.50. return

Syntax:

  {\tt return lisp-object}

Return Values:

  {\tt lisp-object}

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

  {\tt statusp}

    ASCII digit character. (Returns numeric value.)

  {\tt NULL}

    Invalid lisp-object.

Options:

  none

Notes:

  none

## 21.5.51. returns

Syntax:

  {\tt returns lisp-object}

Return Values:

  {\tt string}

  {\tt lisp-object}

Options:

  none

Notes:

  none

## 21.5.52. rfc822

Syntax:

  {\tt rfc822 messagefile}

Return Values:

  {\tt status}

Options:

  none

Notes:

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

## 21.5.53. rfc822date

Syntax:

  {\tt rfc822date}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  Prints the current time in RFC822 format.

## 21.5.54. rfc822syntax

Syntax:

  {\tt rfc822syntax address}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  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.

## 21.5.55. runas

Syntax:

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

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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).

## 21.5.56. sender

Syntax:

  {\tt sender}

Return Values:

  {\tt 1}

    Is a sender address.

  {\tt 0}

    Is not.

Options:

  none

Notes:

  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''.

## 21.5.57. set

Syntax:

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

Return Values:

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

Options:

  {\tt -a}

    Automatically export changed variables.

  {\tt -e}

    Exit on error exit status of any command.

  {\tt -f}

    Disable filename generation (no globbing).

  {\tt -h}

    Hash program locations.

  {\tt -n}

    Read commands but do not execute them.

  {\tt -t}

    Read and execute one command only.

  {\tt -u}

    Unset variables are error on substitution.

  {\tt -v}

    Print shell input lines as they are read.

  {\tt -x}

    Print commands as they are executed.

  {\tt -L}

    Trace LEXER processing (sslWalker).

  {\tt -C}

    Print branch and emit inputs (sslWalker).

  {\tt -P}

    Trace execution (sslWalker).

  {\tt -S}

    Print input buffers when used (sslWalker).

  {\tt -k}

    Not supported option.

  {\tt -}

    Do nothing.

Notes:

  none

## 21.5.58. shift

Syntax:

  {\tt shift [number]}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  Modifies caller's argument vector.

## 21.5.59. sleep

Syntax:

  {\tt sleep number}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  none

## 21.5.60. squirrel

Syntax:

  {\tt squirrel [-]event}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  {\tt -}

    Set flag value to 0.

  {\tt {\(<\)}none>}

    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}

Notes:

  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.

## 21.5.61. stability

Syntax:

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

Return Values:

  {\tt 0}

Options:

  none

Notes:

  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.

## 21.5.62. ``test'', ``[''

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

## 21.5.63. times

Syntax:

  {\tt times }

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  none

## 21.5.64. trace

Syntax:

  {\tt trace key1 ... keyN} Enables tracing of the specified items. The valid keywords are listed in the options below.

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  {\tt all}

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

  {\tt assign}

    Prints shell variable assignments.

  {\tt bind}

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

  {\tt compare}

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

  {\tt db}

    Prints database lookups, including cache search and update information.

  {\tt final}

    Prints the message envelope information after processing each message.

  {\tt functions}

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

  {\tt matched}

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

  {\tt on}

    Same as {\tt functions}.

  {\tt regexp}

    Prints regular expression matching execution.

  {\tt resolv}

    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.

  {\tt rewrite}

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

  {\tt router}

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

  {\tt sequencer}

    Prints the procedural steps taken during message processing.

  {\tt memory}

    Prints memory allocation information after each message.

Notes:

## 21.5.65. trap

Syntax:

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

Return Values:

  {\tt 0}

Options:

  none

Notes:

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

## 21.5.66. type

Syntax:

  {\tt type [command ...]}

Return Values:

  {\tt 0}

Options:

  none

Notes:

  none

## 21.5.67. uid2login

Syntax:

  {\tt uid2login uid}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  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.

## 21.5.68. umask

Syntax:

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

Return Values:

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

Options:

  none

Notes:

  Without parameters default mask is 077.

## 21.5.69. unset

Syntax:

  {\tt unset [variable ...]}

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

  none

Notes:

  none

## 21.5.70. untrace

Syntax:

  {\tt untrace key1 ... keyN} Disables tracing of the specified items.

Return Values:

  {\tt 0}

  {\tt 1}

    Error.

Options:

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

Notes:

## 21.5.71. user

Syntax:

  {\tt user object-reference}

Return Values:

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

Options:

  none

Notes:

  none

## 21.5.72. wait

Syntax:

  {\tt wait [pid]}

Return Values:

  {\tt retcode}

Options:

  none

Notes:

  none

Prev | Home | Next
zmailer(3) | Up | Scheduler