OS/2 Shareware BBS: 2 BBS

home *** CD-ROM | disk | FTP | other *** search

/ OS/2 Shareware BBS: 2 BBS / 02-BBS.zip / MUSHP71.ZIP / MUSH.DOC < prev next >

Wrap

Text File | 1990-12-21 | 238KB | 5,743 lines

MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) NAME The Mail User's Shell - Shell for electronic mail. SYNOPSIS mush [ -n ] [ -v ] [ -s subject ] [ -c cc-list ] [ -b bcc- list ] [ address-list ] mush [ -n ] [ -v ] [ -U[!] ] -h draft-file mush [ mode-options ] [ file-options ] INTRODUCTION The Mail User's Shell (Mush) is an interface for sending and manipulating a database of electronic mail messages under the UNIX(TM) environment. There are three user interfaces that allow the user to interact with Mush. The default interface is the conventional tty-based line mode similar to command line interpreters such as csh as well as other mailers, such as University of California, Berkeley's Mail and Bell Lab's System V mailx interface. This mode requires nothing from the terminal in terms of screen capability and may be run on many different versions of the UNIX(TM) operating system. The text-graphics (curses) interface is reminiscent of the vi visual editor, but is user-configurable to simulate other editors. This interface does not require graphics capabilities of the computer or the terminal on which it is run, but the terminal must have the minimum capabilities required by any visual screen editor. The window interface for the Sun Workstation utilizes the icon and menu based (mouse selectable) windowing system. This tool (graphics) mode is highly subject to the version of operating system your Sun may be running. It is intended to be run on Sun versions 3.5 and higher (those that have the SunView window system). See the corresponding sections for more information on the user interface desired. Most of this manual deals with commands, variables and actions that are common to all three interfaces although some attention is paid to individual characteristics of each interface. The following command line arguments are understood by Mush (full word forms in parentheses): -b bcc-list (-blindcarbon, -blind) The list of Blind Carbon Copy recipients is set on the command line. If more than one address or an address containing spaces is specified, the entire list should be enclosed in quotes. This option applies when sending mail only. If you are entering the shell, curses mode, or the tool Page 1 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) mode, this option is ignored. -C (-curses) Enter the mailer in curses mode upon startup. -c cc-list (-carbon, -copy) The list of Carbon Copy recipients is set on the command line. If more than one address or an address containing spaces is specified, the entire list should be enclosed in quotes. This option applies when sending mail only. If you are entering the shell, curses mode, or the tool mode, this option is ignored. -d (-debug) Turns on the debugging level to 1. You can change debugging levels from within the shell using the debug command. -e (-echo) Normally, the program runs with the local echo off and each character typed is processed individually so as to process certain macros and keyboard mappings. This option will suppress this from taking place and the program will only process input after a carriage return has been hit. Under normal circumstances, this action is transparent to the user and the use of this option is discouraged except when using a debugger with the program. Note that if this option is specified, any key sequence set by map or map! will not take place. This option is ignored for curses mode. -F[!] filename (-source) This file is the same type as the initialization file read on startup (see INITIALIZATION) with the exception that commands that manipulate or search messages may be given. Normally, such commands may not appear in the initialization file since that file is read before the folder is scanned. The file specified by -F is read after the folder is scanned, so commands that affect messages are allowed. The optional `!' argument prevents the shell from running after the file has been sourced. Otherwise, Mush continues into whatever interface has been specified. -f [ filename ] (-folder) The optional filename argument specifies a folder containing mail messages. With no argument, mbox in the current directory (or the variable mbox) is used. If no filename is given, this option must be last on the command line. -H[:c] (-headers) Have Mush display mail headers without entering the shell. See the headers command for Page 2 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) information on the :c argument. No colon modifier is equivalent to "-H:a". This option prevents the shell from running, so this option will turn off the -S and -C flags. This option is ignored if the tool mode is in effect. -h draft-file (-draft) This option specifies a previously prepared message file (called a draft) which will be read in as a new message to be sent. The current implementation requires that the draft file must contain all the message headers; Mush will add only a new "Date:" and a "From:" header if there is none. If there is no "To:" header, the draft will not be sent. See the mail command and the section on "Sending mail" for more information. -I[!] filename (-init) This option specifies an initialization file to be read before any of the other Mush initialization is done. The file specified by -I is read before the default system initialization file is read (see the INITIALIZATION section for details). The optional `!' argument prevents Mush from reading the default system file, so -I! can be used to specify a substitute default file. The user's personal initialization file is read normally. -i (-interact) Forces interactive mode even if input has been redirected to the program. This is intended for remote host mail sessions (with -e) but also allows the user to redirect input from a "script" of Mush commands. See the INITIALIZATION and MUSH SCRIPTS sections for information on how to write scripts that deal with mail. Note that this flag is different from the "ignore" flag of UCB Mail. -m mailbox-path (-mailbox) The mailbox specified will be interpreted as if it were the user's main (system) mailbox in place of /usr/spool/mail/$USER (or whatever path is applicable for your system and Mail Transport Agent). -N (-noheaders) Enter Mush without displaying any message headers. This argument is passed to the folder command. -n[!] (-noinit) No initialization is done on start up. That is, do not source the default system initialization files. If the `!' argument is given, reading of the user's personal .mushrc or .mailrc files is also Page 3 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) suppressed. See the INITIALIZATION section for more information on startup and the significance of these files. -r (-readonly) Initialize the folder in Read-Only mode; no modification of the folder is permitted. This argument is passed on to the folder command. -S (-shell) This flag allows the user to enter the shell even if the system mailbox or specified folder is empty or doesn't exist. -s subject (-subject) The subject is set on the command line using this flag. If the subject has any spaces or tabs, the entire subject should be enclosed in quotes. This applies when sending mail only. If you are entering the shell, curses mode, or the tool mode, this option is ignored. -T timeout (-timeout) In the tool mode (Sun only), timeout specifies the length of time (seconds) to wait between each check for new mail. 30 seconds is the smallest time allowed for performance reasons; 60 seconds is the default value. This option should be used either in place of -t or immediately after it. -t (-tool) Use the graphics tool mode (Sun only). This option must be the first one on the command line, before any Sun window system flags or other Mush options. NOTE: The -t option is obsolete and may be eliminated in future revisions. The preferred way to run the tool mode of Mush is to use the command mushtool, which is a link to mush. -u [ user ] (-user) The mailbox to use is /usr/spool/mail/user. If the login name for user is not specified, then root is used. -U[!] (-send) This option may be used only with -h (-draft). It causes the draft file to be sent immediately without further editing ("unedited", hence -U). If the optional `!' is appended, signatures and fortunes are suppressed. See the mail command and the section on "Sending mail" for more information. -v (-verbose) Verbose mode is turned on. This option is Page 4 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) passed to the actual mail delivery subsystem internal to your version of UNIX(TM). Some mailers do not have a verbose option, so this flag may not apply to your system (System V, for example). This applies when sending mail only. If you are entering the shell, curses mode, or the tool mode, this option is ignored. GENERAL USAGE Because there are three different interfaces available to the user, the tty characteristics (backspace, kill-word, kill-line, redraw line) are simulated identically in all interfaces. When the user has to type something, the 4.2BSD style of tty driver interface is simulated whether you're in the window system, the curses mode, or the tty-line mode, and even on System-V machines. This means that backspacing causes a backspace-space-backspace effect (erasing the character backspaced over). The user may reset his tty characteristics using the stty command. New mail. If during a Mush session, new mail arrives for you, it is automatically incorporated into your system mailbox and you are told that new mail has arrived. In the default line mode, new mail is checked between each command issued. In the curses mode, new mail is checked on each command and is displayed in the bottom line of the screen. In the tool based graphics mode, new mail is checked approximately every minute or the number of seconds specified by the -T option on the command line. If you are using your system mailbox as your "current folder," then the new mail is added immediately to your current list of messages and information similar to the following example is displayed, to tell you whom the mail is from: New mail: (#15) argv@zipcode.com (Dan Heller) If you are not in your system mailbox, then the new mail will not be added to your list of messages, but you will instead be informed of the new arrival. If you are using the tool based mode and Mush is closed to an iconic state, then the number of messages in the current folder is displayed on the mailbox icon and the flag on the mailbox will go up. Displaying messages. Depending on the interface you use, you can display any Page 5 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) message in your list of messages as long as the message is not marked for deletion. If the message is marked as deleted, then use the undelete command supplied by the interface you are using. To display a message in line mode, specify the message using print, type, p, t, or type a message number to display that message on the screen. In curses mode, move the cursor over the message you want and type a `t' or `p' to read the message. You may "bind" other keys to call the function that displays messages if `t' and `p' are uncomfortable. In the tool mode, move the cursor over the header summary of the message you wish to be displayed and select the LEFT mouse button. The MIDDLE mouse button will delete the message, and the RIGHT button will bring up a menu of additional options, including help. If the message you want is not visible (in the header subwindow), you may type the number of the message in the "Range:" item, and press return. That message number will be displayed. Finally, the "Next" item in the panel below the header display can be used to step through the folder, one message at a time. In the line or curses mode, if the message has more lines than the variable crt, then a pager will be invoked to allow the user to page through the message without having it scroll off the screen. The pager used is determined by the variable pager. If that variable is unset, then a default pager will be used. Note that if pager is set, but not to a value, or is set to the value of "internal", then the internal pager is used. The internal pager is very simple; the spacebar displays the next crt lines, carriage return prints the next line, and "q" quits the pager. In the tool mode, if a message is larger than the size of the message subwindow, the scrollbar at the left side of the window may be used to page the message forwards and backwards. The variable crt_win may be set in an initialization file to preset the size of the message display subwindow. An alternative to displaying messages is the top command. This command will print just the top few lines of a message. The number of lines is determined by the variable toplines. If this variable isn't set, top will print a number of lines equal to the value of the variable crt. Sorting mail. Mush allows you to sort your mail according to various constraints such as time, size, status (new, unread, deleted, etc.), author and subject. See the sort command in Page 6 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) the COMMANDS section for more information on sorting. Sorting has a panel item in the tool mode, and is bound by default to the `o' (sort) and `O' (sort reverse) keys in curses mode. Picking specific messages. You can select messages that contain unique information, or from messages that have special attributes. You have the option of restricting your search to messages between dates, message numbers, author names and other constraints. See the pick command in the COMMANDS section for complete details. This feature is not directly accessible from the tool mode, and is available only as a search action in curses mode (see, however, the CURSES INTERFACE section for temporary escapes to line mode). Sending mail. You can send mail by listing addresses on the command line when Mush is started, by using the mail command from within Mush, or by responding to other mail. In curses mode, the `m' key invokes mail, and the `r' key begins a response. In the tool mode, selecting the "Compose" or "Reply" items on the main panel will open a separate frame for message composition. The message replied-to is either the current message or one specified in the "Range:" item. When you are sending mail, you are in a mode where everything you type is added to the contents of the message. When you are done typing your message in line or curses modes, you can type `^D' (control-D) to signify the end of the message. If you have the variable dot set, then you can end a message with a `.' on a line by itself. In the tool mode, select the "Send" item in the composition frame to finish and send the message. While you are composing a message, Mush treats lines beginning with the character `~' specially. This is called a tilde escape. For instance, typing "~i" (alone on a line) will place a copy of the "current message" into your message body. It will not include the message headers of the message, just the body of text that comprises the message. A subset of these escapes are available in the tool mode, and others are provided as panel items or as menu selections from the "Include" item. Tilde escapes which alter message headers are not usable when the variable edit_hdrs is set or when the -E option was passed to the mail command. The tool mode composition window uses header editing at all times, but provides some of these escapes anyway; see the descriptions below, and the description of the edit_hdrs Page 7 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) variable, for complete details. Available tilde escapes: [OPTIONAL arguments in square brackets] ~a file Append message buffer to file name. Accessed via the "Export" panel item in tool mode. ~b [bcc-list] Modify blind carbon recipients; otherwise identical to ~t. In tool mode, moves the cursor to the Bcc: header, adding one if necessary. ~c [cc-list] Modify carbon copy recipients; otherwise identical to ~t. In tool mode, moves the cursor to the Cc: header, adding one if necessary. ~E[!] Erase message buffer; not available in tool mode. Saves the contents of the letter to "dead.letter" (unless the `!' is specified) and then clears the message buffer; the user remains in editing mode. If the variable nosave is set, then `!' need not be specified. ~e [editor] Enter the editor. Defaults to variable editor, environment EDITOR, or vi, except in tool mode, where ~e is equivalent to ~v. ~F[!] Add a fortune [don't add] at end of message. Accessed via the "Fortune" panel item in tool mode. ~f [msg-list] Forward mail. The included messages are not indented, but are marked as "forwarded mail". Accessed via the "Include" panel item in tool mode. ~h Modify all message headers. Each header is displayed one by one and each may be edited. In tool mode, moves to the To: header; typing a carriage return will advance the input cursor to each of the other headers in turn. The mouse cursor will change to a "bent arrow" when automatic input cursor advance is active. ~I [msg-list] Same as ~i, but also include the message headers. Accessed via the "Include" panel item in tool mode. Page 8 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) ~i [msg-list] Include the body of the current message (or listed messages). Accessed via the "Include" panel item in tool mode. See the descriptions of the variables indent_str, pre_indent_str, and post_indent_str. ~p [pager] Page the message body; not available in tool mode. Defaults to variable pager, environment PAGER, or the default pager set up by the system administrator. This may be the internal pager. ~q Quit message; save in ~/dead.letter if nosave is not set. Not available in tool mode. ~r file Read filename into message buffer. Accessed via the "Import" panel item in tool mode. ~S[!] Include [don't include] signature at end of message. The variables autosign and autosign2 describe the file or string to append to the message. See the VARIABLES section for more information on these variables. Accessed via the "Autosign" panel item in tool mode. ~s [subject] Modify the subject header. In tool mode, moves to the Subject: header, adding one if necessary. In other modes, if an argument is given (a new subject), then the subject line is replaced by the new subject line. If none is given, then the subject line is displayed for editing just as in the ~t command. ~t [list] Change list of recipients ("To" list). In tool mode, moves the cursor to the To: header. In other modes, if a list is given, this list is appended to the current list. If no list is given, then the current list is displayed and the cursor placed at the end of the list. You can backspace over the stuff in the list or you can append more addresses onto the end of the list as desired. ~u Up one line; not available in tool mode. If the user made a mistake typing a letter and he has already hit carriage return, he may avoid entering the editor and edit the previous line using ~u. The line is retyped and the cursor is placed at the end allowing the user to backspace over it and retype the line. System-V users should note that if the new line is shorter than it was before the ~u command, the line is padded with Page 9 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) blanks to the previous length of the file. ~v [editor] Enter the visual editor; works in tool mode. Also accessible through the "Edit" button in tool mode. Defaults to variable visual, environment VISUAL, or vi. ~w file Write message buffer to the indicated file. Accessible in tool mode via the "Export" panel item. When the header editing is in use (the variable edit_hdrs or the -E option of mail), this tilde-command can be used to create a draft file. Draft files are partially completed letters that you wish to save for editing and eventually sending later. See the mail command for a description of rereading and sending drafts. ~x Exit message; don't save in dead.letter. Accessible in tool mode via the "Abort" panel item. ~$variable Insert the string value for variable into message; not available in tool mode. If a boolean variable is listed, nothing is appended regardless of its value. ~:command Run the Mush command specified by "command"; not available in tool mode. You may not run any command that sends mail. It is inadvisable to change folders at this time since the current message list may be corrupted, but the action is allowed nonetheless to provide flexibility for experienced users. ~~ A line beginning with two escape characters will be unaffected by Mush except that only a single tilde will be inserted into the letter. The variable escape may be set to describe a character other than `~' to be used as the escape character. However, tilde escapes are normally NOT interpreted when Mush is started with redirected input. If tilde-interpretation is desired, use the -i option when starting mush. Mail Aliases. Mail aliases are shorthand names for long mail addresses. These are supported in the same manner as UCB Mail supports them. Because Mush has command line history reminiscent of csh, commands that use UUCP's `!' character for user-host and host-host separation should be escaped (preceded by a backslash). This is not necessary in the initialization file (.mushrc) because history referencing is ignored while Page 10 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) these files are being sourced. See the INITIALIZATION and LINE-MODE INTERFACE sections for more information on initialization file format and the history mechanism. Aliases reference normal mailing addresses as well as other aliases. If a loop is detected, then the user will be notified and the message will be forced into the file dead.letter in the user's home directory. The unalias command is used to reverse the effects of the alias command. From the tool mode, aliases can be set and unset in an aliases subwindow. Press the RIGHT mouse button on the "Options" item in the main frame, and select "Aliases" from the menu. Help. Mush was designed so that each command or action should not be a mystery. Helping the user understand what to do and how to do whatever he wishes is the goal behind the help facility. For this reason, the help command gives information on both general usage and a few specific help categories. In text mode, most help is gotten by typing -? as an argument to a command. Almost every command has the -? option. When this option is specified, most commands will attempt to read from a help file a brief explanation of the functionality of the command. If necessary, a pointer to other sources of information will be given to fully explain a concept. In line mode, typing `?' as a command will display a list of possible commands. In the curses mode, the `?' key will display help message, which explains how to obtain a list of the current key-to-command bindings; a keystroke or set of keystrokes correspond directly to a command. In the tool mode, this is also available, but more extensive help is provided in the pop-up menus. Press the RIGHT mouse button (the "menu button") when pointing to any panel button and a number of items will appear in a menu. The last command in the menu list will often be one labelled "help". If a button does not have a menu or has no help item, check the menu of the "Help" button for related topics. Selecting any help item will open a new scrollable window with help text. Note: The limited number of file descriptors in SunOS 3.5 forces Mush to display help information in the message window in the main frame. INITIALIZATION After the command line arguments have been interpreted Mush will read commands from one or more initialization files Page 11 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) that (typically) set variable values, aliases, command line aliases, and so forth. Any file specified by the -I option is read first. Next, if neither -I! nor -n was given, a default system initialization file is read. The system default file is set up by the system administrator and may contain commands that should be set system-wide. Finally, if -n! was not given, Mush reads the user's personal initialization file. The user's file is determined by first looking for the environment variables MUSHRC or MAILRC. If neither of those environment variables is set, then the file .mushrc is searched for in the home directory of the user. If that file cannot be found, Mush will attempt to read the file .mailrc from the same directory. Finally, if that file cannot be read, no initialization is done and the default values will be in effect. If the user has no home directory, or permissions prevent read/write access to $HOME, /tmp is used as the home directory. See the home variable under the VARIABLES section. Once in the shell, the source command may be used to specify a file if you want to read commands from a file other than the default. The command saveopts will save all variable settings, aliases, and all other Mush settable attributes, to aid in creating an initialization file. If no filename is given on the command line, the source and saveopts commands choose a file in the manner described above. Saveopts will not overwrite the file if it exists. In such cases, you will be prompted to confirm overwrite. If you confirm overwriting the existing file, remember that existing "if" expressions or other manually entered comments or non variable-setting type commands that previously existed in the file will be lost. No interactive commands should be called from any initialization file. These commands are not prevented because it is impossible to trace which commands are actually UNIX(TM) commands that will be interactive. The responsibility of not running interactive commands is left to the user. Because the initialization file is read before any messages are read into the program, message filtering commands should not be placed in this file unless you know you're going to re-source the file later as a command. Initialization File Format. When reading the initialization file, Mush will recognize the `#' character as a comment character. It may be anywhere on a line in the file. When that character is encountered, processing of that line is discontinued to the end of the line. If the `#' is enclosed Page 12 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) in quotes (single or double), then it is not considered a comment. Examples: set shell = /bin/csh # set the shell variable # this entire line has been commented out. set prompt = "Message #%m: " # The `#' is within quotes The exit command has special meaning in the initialization file. If the command is found, Mush will not exit, but rather, discontinue reading from the file immediately. There may be "if" expressions within the initialization file to determine certain runtime states of Mush. No parentheses are allowed and only one boolean expression may be evaluated per line; that is, no "&&" or "||" may be used in expressions. An "else" on a line by itself may precede alternative actions. "If" expressions may be nested to any reasonable depth, but there must always be an "endif" matching each "if" expression. The statements associated with an "if" expression are never on the same line with the conditional expression. Conditional expressions understood include the internal variables istool, iscurses, is_shell, hdrs_only, is_sending, and redirect. These are internal variables whose values cannot be referenced using the "$variable" method of variable expansion. If istool is true, the program is going to run in the tool mode. If iscurses is true, the program is in or is going to run in the curses mode even though the screen package may not yet have been started. If is_shell is true, then Mush has entered the shell; is_shell is always false at startup when initialization files are read, and is always true when files are sourced after initialization with the source command or the -F option. If hdrs_only is true, then the -H flag on the command line has been given. If is_sending is true, then the user is sending mail to another user. This does not imply that the user is not going to be running a shell after the mail is sent. If redirect is true, then input to the program is redirected. The test for redirection tells whether input, not output, has been redirected to the program. The -i option on the command line is required to run the shell if redirect is on. If -i is specified, the value for redirect will be set to false. Note that any time Mush runs when not connected to a terminal, it will believe that input has been redirected. See the MUSH SCRIPTS section for more details. The `!' operator may be used to negate expressions, thus, if !istool exit Page 13 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) else set autoprint endif means that if you are not running as a tool, stop reading commands from this file. Otherwise, set the autoprint variable. set hdr_format = "%25f %7d (%l/%c) %25s" if hdrs_only exit endif This tells the program to set the hdr_format variable and check to see if we're running the program to read headers only. If so, stop reading this file (exit) and continue on with the program. This speeds up runtime quite a bit for those who have lengthy initialization files, because no other shell variables are necessary. if !iscurses set crt = 24 screen = 18 endif This segment checks to see that we're not running in curses mode, and if not it will set our crt and screen sizes. This is mostly because the curses mode will set those values for us by looking at the size of the screen. See the CURSES INTERFACE section for configuring your environment so you enter curses mode each time you run the shell. String evaluation is allowed in "if" expressions, and the operators "==" and "!=" may be used to determine equality or inequality, and "=~" and "!~" may be used for pattern- matching. Usually, variables are compared with constants for evaluation. Note that it is not possible to compare variables to an empty string, and variables that evaluate to an empty string may cause errors. It is possible to test whether a variable is set by using the syntax "$?variable" (as in csh) but there is not currently any way to test for an empty string value. if $TERM == adm3a set pager = more else set pager = less endif This segment tests to see if the user's terminal type is "adm3a". If it is, then it sets the pager variable to be Page 14 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) the more program. Note that the variable TERM will be gotten from the user's environment if a shell variable is not set already. Otherwise, the pager variable is set to "less". This exemplifies the fact that less frequently fails to function correctly for the terminal type "adm3a" so we don't use it. Also supported in "if" expressions are the test flags "-e" and "-z". These flags test to see if a file exists ("-e") or if it is zero-length ("-z"). These are most useful in command files that are to be read after the shell has started; see the examples in the MUSH SCRIPTS section. After sourcing the initialization file, Mush reads all the mail out of the specified folder (the system spool directory if no folder is given) and creates a list of messages. The current maximum number of messages the user can load is set to 1000 by default. The system administrator who configures the program can reset this value higher or lower if you ask nicely. If the user has the sort variable set, then when the current folder's messages have all been read, the messages are sorted according to the value of the variable (see the sort entry under the VARIABLES heading for more information). Each message has a number of message header lines that contain information about whom the mail is from, the subject of the message, the date it was received, and other information about the letter. This information is then compiled into a one-line summary for each message and is printed out in an appropriate manner depending on the interface you're using. At this point, commands may be input by the user. Lengthy or complex commands can be placed in a file and then executed via the source command. Such files use the same format as the initialization files and may use all the same tests in "if" expressions. Sourcing of a file of filter commands such as those in the example above can be automated by using the -F option when Mush is started. Also see the MUSH SCRIPTS section for other uses. LINE-MODE INTERFACE In the line-mode, the user is given a prompt to which commands are issued and arguments are passed to commands. When the user types at the prompt, each line is parsed and words (or arguments) are separated into an array of strings. This array, also called an argument vector, is then modified by expanding history references, command line aliases, and variable references. A command line ends when the end of the line is encountered or a pipe (|) or semicolon (;) character is encountered, separating discrete commands. When a command line has been parsed and placed in an Page 15 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) argument vector, the first argument in the vector (the "command") is searched for in a list of legal Mush commands. If found, the function associated with that command is called and the rest of the line is passed to that function as command line arguments. Before commands are called, however, the input the user gives is preprocessed in a style reminiscent of the C-shell (csh). Mush also supports a subset from each of the following aspects of csh: +o Command history. +o Command line aliasing. +o "Piping" mechanism to redirect "input" and "output" of commands. +o Filename metacharacters. Command history. Mush supports a history mechanism similar to that supplied by csh. A subset of csh history modifiers are supported to reference previously issued commands and to extract specified arguments from these commands. The history mechanism remembers a list of past commands whose length is bounded by the value of the history variable. If this variable is not set, only the most recent command is remembered. To reference previously typed commands, the `!' character is used in the same manner as in csh. There is a limited implementation of history modification; supported are the argument selectors that reference command line arguments and ":p" (echo, but don't execute the command). Examples: !-2:$ two commands ago, last argument. !3:2-4 the third command, arguments two through four. !!:p print the last command in its entirety. During the sourcing of initialization files (.mushrc), history is not in effect and therefore the `!' character does not cause history expansion. This includes startup of the program and when the command source is issued. UUCP style addresses that contain the `!' character may be given in the initialization file without the need to be preceded by a backslash. However, `!' does need to be escaped if cmd's are used to reference command line arguments. Command line aliasing. Command aliases are different from mail aliases in that they are used to expand to commands. This feature enables command substitution similar to csh. To be backwards Page 16 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) compatible with UCB Mail, the alias command is used for address aliasing. Thus, the command cmd is introduced in place of alias. Examples: cmd d delete cmd t type cmd dt 'd ; t' cmd - previous cmd r 'reply \!* -e -i' In the last example, if the user types "r 5", Mush will reply to sender of the fifth message and pass all the other arguments along to the reply command. Note the escaping of the `!' character. This must also be done if set in the initialization file (.mushrc). Had the user not specified a message number on the `r' command line, reply would respond to the "current message" rather than the fifth message. Piping commands. Mush commands can be "piped" to one another so as to provide output of one command to be used as input to the next command in the pipeline. However, the output of commands is not the "text" that is returned (as it is in sh and csh), but instead is a message list of the messages that were affected. A message list is defined as the set of messages that the user specifies in a command or the messages a command affects after it is through executing. When one command is piped to another, the effect is that the second command will consider only those messages affected by the first command. In most cases, Mush is smart enough to know when piping is occurring and may suppress text output that a command might produce. Examples: pick -f fred | save fred_mail This will find all the messages from "fred" and save them all in the file named fred_mail. lpr 4-8 | delete This will send messages 4, 5, 6, 7, and 8 to the printer and then delete them. headers :o | delete Deletes all old (already read) mail. Because action is taken on mail messages, not files, Page 17 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) metacharacters such as `*' and `?' are not expanded to file names as csh would do. Instead, Mush commands take message lists as arguments (a list references one or messages) to take action upon. When referencing message numbers, Mush understands the following special syntax: * All messages ^ The first message $ The last message . The current message N-M A range of messages between N and M, inclusive In the last case, N and M may be * ^ $ . or digits referencing explicit message numbers. The range must be in ascending order. You can also negate messages by placing the message list inside braces, `{' `}' -- thus, the expression "2-19 {11- 14}" references messages 2 through 19 except for messages 11 through 14. Note that message lists are parsed left to right. Negated messages may be reset by turning them on again later in the argument list. A common error new users make is to specify a negated list without specifying any beginning messages. delete { 6 } In this example, the user attempted to delete all messages except for number 6. He should have specified `*' beforehand. A correct example: preserve ^-. { 3 } Here, the user specifies a valid message list and causes Mush to preserve all messages from the beginning of the list (message 1) to the current message, excluding message 3. As discussed, after the command line is parsed, the command given is called and the rest of the arguments on the command line are passed to it. If no Mush command has been found that matches the one given, then the variable unix is checked. If it is set, Mush attempts to run the command line as a UNIX(TM) command. If unix is not set, or if the command could not be found in the user's PATH environment, a message will be printed indicating that the command was not found. Since no "messages" are affected by UNIX commands, those that appear within Mush pipelines are executed by the pipe command. A UNIX command may never be the first command in a Page 18 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) pipeline unless the pipe command is used explicitly. If the user wishes to execute UNIX commands that are to be piped to one another (or use any sort of redirection), the command sh is provided for such purposes. Since Mush will parse the entire command line, caution should be taken to enclose questionable shell variables or metacharacters with quotes to prevent Mush from expanding them. See the COMMANDS heading below for more detail. This shell-like quality is for the convenience of the user and is not intended to replace the functionality of sh, csh, or any other command interpreter. Filename metacharacters. Mush's command interpreter does not normally pre-expand metacharacters in the manner of other shells, because the metacharacters may refer to either messages or files. Instead, those commands that deal with file names do any necessary metacharacter expansion. Two metacharacters are nearly always recognized: `~' refers to the user's home directory, and `+' refers to the user's folder directory ("~/Mail" or the value of the variable folder). Another user's home directory can also be referenced as "~username", and for this reason files in the user's home directory must be referenced as "~/filename". However, the `/' character is optional when referring to folders; that is, "+filename" and "+/filename" both refer to the same file in the folder directory. If filename completion is enabled by setting the variable complete, the command interpreter will expand csh-style metacharacters when completing filenames. A completion containing metacharacters expands to all the files matching the pattern when the completion key is pressed (defaults to ESC, `^['). See the description of complete for limitations of this facility. CURSES INTERFACE The curses interface utilizes the curses routines intrinsic to most UNIX systems. This interface is screen oriented rather than line oriented and allows the user to access commands and messages more quickly at the cost of history, piping, and a few commands. Many users who prefer the curses interface might want to always start all their mail sessions in the curses interface. Putting the curses command in your initialization file is allowed, but you can also create an alias or function in your login shell to always use the -C option. Mush will attempt to know not to run a shell if you're just sending mail to someone, so the csh command Page 19 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) sequences: % alias mail 'mush -C' % mail fred will mail to fred and not enter the shell. However, if you just said "mail" with no arguments, you'll enter the shell in curses mode if you have mail. If you don't, you'll be told so, and the shell will not start. If you want to enter curses mode even if you don't have mail, use the -S option on the command line. In curses mode, the user's terminal has its "echo" turned off so commands that are issued are not echoed on the screen. Certain commands cause the mode to return to normal for typing purposes (sending mail, for example). In normal operation, the screen will display the current set of message headers, the current message number is in the top left corner, the mail status on the top line, and the cursor will be placed on the current message. The number of message headers displayed is set by the variable screen. If the user does not have that variable set, the baud rate is checked and the size of the screen is set according to optimal refresh time. Usually, 300 baud gives 7 lines, 1200 gives 14, 2400 gives 22 lines, and all higher baud rates give the size of the screen, whatever that may be. Note that the top line is reserved for "status" and the bottom line is for user interaction should it be required. The user may now type commands via key sequences that are not echoed to the screen. Thus, function keys may be bound to "commands" by using the bind command. A list of key-to- command bindings can be found at runtime by typing `?' in curses mode or by using the bind command in line mode. The commands to which you can map sequences are intended to be as self explanatory as possible, but admittedly, it might be easier to figure out via trial and error than to try to wade through this documentation. A list of the legal curses commands can be obtained when executing the bind command. Regular tty line-mode commands are not issued from the curses interface; only special curses mode commands are understood. The current list of valid curses commands is: alias last-msg screen-back back-msg line-mode screen-next bind lpr search-again bind-macro mail search-back bottom-page mail-flags search-next chdir map shell-escape copy map! sort copy-list my-hdrs sort-reverse Page 20 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) delete next-msg source delete-list preserve top display quit top-page display-next quit! unbind exit redraw undelete exit! reply undelete-list first-msg reply-all update folder reverse-video variable goto-msg save version help save-list write ignore saveopts write-list The following is a list of default key-command bindings. If you specify bind commands in your initialization file that conflict with these defaults, your settings will override the defaults. The default settings given in this manual use the ^-character method to indicate control characters (mostly because nroff makes printing the backslash character so amazingly difficult). Thus, `^X' would mean control-X even though you'd have to type "\CX" to set the binding and actually use the control key and the `X' key simultaneously to really do a Control-X. ., t, p, T=top, n=next Display (type/print) message. Top will display the first crt lines of a message. Next will print the next message. If the current message is deleted, the next undeleted message is found. You might notice this is different from the line mode, which will return an error message that the current message is marked as deleted. +, j, J, RETURN Go to next message. -, k, K, ^K Go to previous message. ^, $ Go to first/last message. {, } Go to top/bottom of screen. a Set aliases. b, B Set/unset bindings. d, D, u, U Delete/undelete messages (capitals prompt for message list). f Change folder. If current folder has changed, Page 21 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) verification for update will be requested. g, 0-9 Go directly to a specified message. When the "goto" command is selected, a prompt at the bottom of the window prompts for a message list. Anything that describes a message list may be used. Since Mush commands return message lists, a legal Mush command enclosed in backquotes may be used to go to a particular message. The new current message pointer will point to the next message, returned by the command, that is below the old current message. An example: goto msg: `pick -f argv` This will cause the current message to move to the first message in the current folder from the user "argv" that comes after the message pointed to when the "goto" was issued. So, if messages 1 and 5 are from the user "argv" and the current message the user was on was message 3, then the new current message would be message 5, since it is the first message found after message 3 that is from "argv". If none of the messages are found after the current message, the new current message will be the first one returned by the command. h Set personal headers. i Set ignored headers. m, M Send mail (capital prompts for mail flags). o, O Order messages (sort; capital reverses order). A prompt requests the sort constraints. q, Q, x, X Quit/exit. `q' will test to see if the current folder has been updated and prompt the user to verify updating. `x' does not update mail, but quits the program. `Q' does not prompt for update verification; if changes were made, updating is automatic. `Q' (quit!) and `X' (exit!) will work even when typed at the "...continue..." prompt, whereas `q' and `x' will not. r, R Reply/reply all. s, S, c, C, w, W Save, copy, or write messages (capitals prompt for message lists). Page 22 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) v Set regular variables (as opposed to environment variables). V Print version number. z, Z Print next/previous screenful of message headers. ^L Redraw the screen. ^P Preserve current message (toggle). ^U Update folder. A prompt will request confirmation. ^R Toggle reverse video mode (current message is in reverse video). | Send message to printer ! Shell Escape. Prompts for command; RETURN invokes a shell. % change directory. (, ) Source/saveopts. Prompts for file name. /, ^/, ^N Forward, backward, continue search for patterns. Entire messages are not searched for here. Only the text available on the screen is searched for. Note that some terminals use `^_' (control-underscore) for `^/', so you may wish to re-bind this key. && Create a curses mode macro. &: Create a line mode macro. &! Create a composition mode macro. :[cmd] Enter line mode for one command. History is not recorded for this escape, and line mode macros are not available. If no command is given, curses mode is exited and the session continues in line mode (in which case history and macros become available). When setting new key sequences to be bound to commands, the user may use control keys and the ESCAPE character for extended commands. Exceptions are control-C, control-\, and possibly other control characters depending on your system's configuration or your current tty mode settings. When assigning key sequences to commands, the user enters Page 23 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) the bind command and prompting is done. If the user wishes to have control characters or the escape character in a key sequence while still using ASCII format, a special notation for control characters is provided. This sequence is used primarily for the use of binding control character sequences in the initialization file. This format is also used to display the current key-command mappings by the program. To specify control characters in ASCII format for the bind command, the sequence "\Cc" is used where `c' is the character that the control key will translate to and must be in upper case. The sequence "\CP" would map to control-P. If the user wishes to indicate the RETURN key, this is specified with the string "\n" and the tab key is specified by the string "\t". As a more complex example, on a Wyse-50 terminal, the 8th function key outputs the three characters: control-A, H, line-feed. To map this function key to a command, the user would have to enter the sequence "\CAH\n" as the key sequence, then follow up with a valid curses command. From then on, if the user presses that function key, the command mapped to it will be executed. The ESCAPE key is signified by the sequence, "\E". On a Sun-3 workstation, the R1 key outputs the character sequence: ESC, [, 2, 0, 8, z. The corresponding bind key sequence would be "\E[208z". Restrictions are that key sequences may not contain the space character unless bound in line mode, and can never begin with a digit. Whenever a command is entered, other than `^L' (redraw), which causes the screen to scroll or be refreshed in any way, Mush is left in the continue mode. When in this mode, the user is given his line-mode prompt followed by "...continue..." indicating that he may issue a new command or return to the top level where the current message headers are displayed on the screen. Remember that this is still the curses mode, but much time is saved by avoiding redrawing the screen after each command. The user may move up and down messages using the appropriate commands (j/k by default) or anything else the curses mode allows. Only the exit and quit commands will return to the top level. Because of this, there are 2 additional ways to "quit" from curses mode and return to the login shell. The "exit" and "quit" commands will quit from the top level, but the commands exit! and quit! are used to exit from the "continue" level in the curses interface as well as from the top level. Note that the best way to understand the curses interface is to just use it. In line mode, the command "curses" puts you into curses mode. Page 24 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) GRAPHICS TOOL INTERFACE When running the window-based tool interface, there will be five subwindows: a panel for folder-related commands and general options, a scrollable display of message header summaries, another panel of message manipulation commands, a four-line scrollable window for warnings and output from certain commands, and a larger window which is used for displaying messages. The message display and command output windows can be scrolled with the up and down cursor keys (function keys R8 and R14 by default), and also recognize "vi" movements (j, k, ^U, ^D, etc.), in addition to having scrollbars. In the header summary window, pressing the LEFT mouse button while pointing at a message header displays that message in the large message window at the bottom of the frame. Pressing the middle button deletes the message, and pressing the RIGHT mouse button displays a menu of actions that will affect the message. Possible actions are to display the message, delete or undelete it, reply to it, save it, preserve it (see the preserve command), or print it (hardcopy). All panel items in the frame have labels describing their functionality. Selecting a panel item with the LEFT mouse button causes the action to be executed. The RIGHT mouse button displays a menu of options that the command may branch to. For example, the Save panel item by default will save messages to the file "mbox", but the RIGHT mouse button causes a menu to be displayed, and the choices of where to save the message increase to include the items in the menu. These typically include the files in the user's folder directory (see the folder variable below). At the end of most lists of menu entries for panel items is an item labelled "help". When this item is chosen, an new window is opened where help for that command is displayed. Note: The limited number of file descriptors in SunOS 3.5 forces Mush to display help information in the message window in the main frame. When composing letters, a separate frame is created which includes a panel of command items, a four-line scrollable window, and a large window for editing the letter. Panel items for including messages, editing (via your usual text editor), sending, aborting the message, and various other manipulations are supplied. See the section on "Sending mail", under the summary of tilde escapes, for more details of composition frame command items. As long as the composition frame is open, all Mush command output is redirected from the small window in the main frame to the small window here. Note: This subwindow is not present in Page 25 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) SunOS 3.5 due to the limited number of file descriptors; command output stays in the main frame in that case. The SunView textsw interface is used by default in the large window for paging and editing. Cursor movement with the function keys (R8, R10, R12, and R14 by default) is supported. COMMANDS Described below are legal commands understood by Mush that you can type at the line mode prompt. Most commands have abbreviations (given in parentheses) and can be followed by message lists. In most cases, whitespace is not necessary to separate commands from message lists. For example, "d*" will delete all messages, and "u1-7 {4}" will undelete messages 1 through 7 except for message number 4. NOTE: This "token splitting" may have unexpected side effects, especially for UNIX commands whose names contain digits. The ability to customize commands using the cmd facility allows users to customize Mush to resemble other mailers. However, efforts have already been made to include commands that are backwards compatible with other line-mode mailers. Users of the graphics tool mode of Mush may have little need for the command line mode because the icon based interface allows interaction with many commands. The tool mode is much more restrictive in favor of a simpler, user friendly interface, but most useful commands may be achieved anyway. The following is a list of all recognized commands. Since most commands accept a message list as an argument, arguments are noted only when they differ from a message list. alias [name] [address-list] unalias name The alias command defines a name to stand for a list of addresses. The defined name can then be substituted for the entire list when sending mail. For example, alias dan dheller@cory.berkeley.edu argv@zipcode.com This defines the name "dan" to be shorthand for two addresses, both of which happen to be Dan Heller. The command unalias can be used to remove an alias definition. With no arguments, alias prints out all the current aliases. With one argument, it prints the list associated with that name, and with more than one argument, it creates a new alias. Page 26 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) alternates [host-list] [!path!login] [*[user]] (alts) This command is useful if you have accounts on several machines. It can be used to inform Mush that your login name at each of the listed hosts is really you. When you reply to messages, Mush will not send a copy of the message to your login name at any of the hosts listed on the alternates list. If the special symbol "*" is used, then your login name is matched against all pathnames and local addresses. A user name may be appended to the "*", in which case that name is matched instead of your login name. If you have another login name on the local or remote machine, then that login may be specified by preceding the login name or the path to the login name by a `!' character. For example, alts zipcode maui1 !cory.berkeley.edu!dheller !root are all either hostnames or pathnames to my other accounts. The last item, "!root" will match root that is only destined for my workstation. Root accounts elsewhere are not considered to be me. If the alternates command is given with no arguments, the current set of alternate names is displayed. await [-T timeout] Directs the shell to wait for the arrival of new mail. New mail is checked approximately every 30 seconds, or every timeout seconds as specified by the -T option. This command does not return until new mail arrives or until a keyboard interrupt (^C) is typed. Unless the string "await" appears in the value of the variable quiet, the terminal bell will ring when await reads in a new message (see the VARIABLES section for details). bind [string [command [parameters]]] unbind string Bind the sequence of keystrokes specified by string to the curses-mode function, command. The string is usually one or two characters, or a sequence sent by one of the "function keys" of a particular terminal. See the CURSES INTERFACE section for a complete list of curses-mode functions; this interface is not available on all systems. The parameters are currently recognized only for the special macro function; see the bind-macro command for details. If no arguments are given to bind, the current set of Page 27 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) curses bindings are listed; if only a string argument is given, the binding for that string is listed; and if both a string and a command are given, a curses binding is created such that when the string is typed in curses mode, the function specified by command will be executed. Bindings can be removed by using the unbind command. bind-macro [string [expansion]] This command is an abbreviation, which invokes the bind command with the special function macro as the second argument. The effect of binding a curses macro is that whenever the string is typed in curses mode, the effect is the same as if the expansion had been typed instead. A special syntax is provided for including non-printing (control) characters in both the string and the expansion; see the CURSES INTERFACE section and the MACROS section for details. If no arguments are given, bind-macro will list the current curses mode macros. It is otherwise identical to bind string macro expansion. cd Change the working directory to that specified, if given. If no directory is given, then changes to the user's home directory. cmd [name [command]] uncmd name Command line aliases are set and unset using these commands. More extensive information is given in the LINE-MODE INTERFACE section. Uncmd may take `*' as an argument to uncmd everything set. curses [off] The curses command causes Mush to change from the line-oriented mode to the screen-oriented (curses) mode, as described above in the CURSES INTERFACE section. This command may not be given when curses mode is already active. When used in an initialization file (such as .mushrc) this command is the same as giving the -C (-curses) switch on the mush command line. The argument off may be used only in initialization files, including those read with -I (-init), and has the effect of turning off the -C switch. Off is ignored at all other times, even in files read with -F (-source). Page 28 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) debug [N] Set debugging level to N (1 by default). When in debug mode, the user can see some of the flow of control the program makes while executing. The intent of the debug level is for tracking down bugs with the program at specific locations. Occasionally, the program may segmentation fault and core dump. When this happens, the user can reenter the program, set the debugging level and recreate the problem. If the user suspects memory allocation problems, a debugging level of 5 or higher will prevent memory from being freed so that memory bounds won't get overwritten. If the user suspects Mail Transport Agent errors, a debugging level of 3 or higher will prevent the MTA from starting and outgoing mail is directed to the standard output instead of actually being sent. delete/undelete (d/u) Takes a message list as argument and marks them all as deleted. Deleted messages will not be saved in mbox, nor will they be available for most other commands. If the folder has not been updated, deleted messages can be recovered with undelete. dt Deletes the current message and prints the next message. echo [-n] [-h | -p] arguments Echoes all the arguments given on the command line, expanding variables and history references. If the -n flag is given, then no newline is appended. If the -h flag is given, then echo looks for formatting parameters as if the "from" command were given on the "current" message. If the -p flag is given, then echo looks for formatting parameters as if your prompt were changed temporarily. Examples: echo -h This message is from %a and is dated %d. might produce: This message is from zipcode!argv and is dated Dec 14, 1988. echo -p There are %n new messages to read in %f. might produce: There are 5 new messages to read in /usr/spool/mail/argv. Note that -h and -p cannot be specified together. Page 29 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) edit (e, v) This function lets you edit messages in your folder. When editing messages, be careful not to remove certain message headers such as Date or From or any others that looks important. If you remove or change something you shouldn't have, you will be notified and the temporary file used to edit the message will not be removed. eval [-h | -p] arg ... As in most shells, the list of arguments to eval is re-parsed and then executed as a command. This is useful primarily for causing multiple levels of variable expansion. If the -h option is given, eval will expand header format strings in the argument list before executing the command. Similarly, the -p option will expand prompt format strings in the argument list before executing. These formats are expanded last, after all history and variable expansion is completed, and are implicitly quoted, so embedded quotes, spaces, tabs, `!'s, etc. are handled correctly. Header formats are expanded using the current message. For example, eval -h pick -f %a will find all messages from the same author as the current message. See the the entries for hdr_format and prompt in the VARIABLES section for more details. Note that -h and -p cannot be specified together. exit (x) Returns immediately to the login shell without modifying the current folder or system spool directory. expand alias-list Aliases, given as arguments, are expanded as they would be if you were to send mail to each. flags [ [ + | - ] [ D f N O P p R r S U ] ] [msg-list] This command modifies the flag bits set on the listed messages. It should not normally be needed, but is provided to allow users, through the cmd facility, to alter the ways that certain conditions are recorded. Multiple flag bits may be set or modified at once. The modifiable flag bits are: D deleted f forwarded N new O old P preserved Page 30 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) p printed R read r replied-to S saved U unread If a `+' or `-' is included in the list of bits, the specified bits are turned on or off respectively, without modifying other bits. If no `+' or `-' is given, then the list of bits is set explicitly and all other bits are lost. The `-' modifier can be escaped with a backslash (i.e., "\-") to prevent its interpretation as part of a message range, or it may be given after the list of bits for the same reason. Message lists can be piped to the flags command; for example, you may use cmd r 'flags \!* + r | reply' to mark as replied-to all messages included in a reply. folder [-N] [-n] [-r] [ %[user] | # | & | file ] (fo) Change current folder. With no arguments, prints the name of the current folder. The arguments are: -N No headers are displayed upon entering new folder -n The current folder is not updated -r Set Read-Only mode (can't alter new folder) %[user] Change to /usr/spool/mail/[user] (default is yours) # Switch back to the previous folder & Change folder to $mbox (default is ~/mbox) File names that do not begin with `/' are interpreted relative to the current directory unless they begin with one of the metacharacters `+' or `~'. As in csh, the character `~' expands to the user's home directory (or to some other user's home directory if used as "~username"). The character `+' is expanded to the name of the user's folder directory (defaults to "~/Mail" or the value of the variable folder). For compatibility with other mailers, no `/' character needs to appear between the `+' and the name of the folder (see "Filename metacharacters" in the LINE-MODE INTERFACE section). This command can only appear in a pipeline if it is the first command; it returns a list of all the messages in the new folder. This command cannot be used in initialization files before the shell has started. For compatibility with older versions, the argument `!' with no leading `-' is interpreted as -n. Page 31 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) folders List the names of the folders in your folder directory. Your folder directory is the directory Mail in your home directory. Or, you can set the variable folder to specify another folder directory. from [ + | - ] [msg-list] [pattern] (f) With no arguments, from will print the current message's header summary (see the variable hdr_format). If given a pattern, from will print the headers of those messages whose "From: " lines match the pattern. When a message list precedes the pattern, or when a message list is supplied by a pipeline, the search is restricted to that list. If only a message list is given (or piped), from will print the headers of the listed messages. The special arguments `-' and `+' can be given to move the current message pointer to the previous or next message, respectively, while also printing that message's header. If a message list was given in addition to `-' or `+', then the current message pointer will be set to the first or last message, respectively, in the message list given. Examples: from + Dan will print the headers of all messages that contain "Dan" in in the author's name and set the current message pointer to the last one of that kind in the list. from - 10-30 {16} will print the headers of messages 10 through 30 except for message 16 and set the current message pointer to 10. from + will print the header of the message after the current message and increment the current message pointer to the next message. from $ will print the last message's header and not move the current message pointer. headers [ [-H][:c] ] [ + | - ] (h, z) Prints a screenful of message headers listed in the current folder. If a message number is given on Page 32 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) the command line, the first message of the screenful of messages will be that message number. The `z' command is identical to the "h +" command and remains for compatibility reasons. The variable screen may be set to tell how many headers are in a screenful. In the graphics tool mode, the variable screen_win contains the number of headers used in the headers subwindow. A typical header may look like: 5 >N argv@spam.istc.sri.com Feb 19, (10/278) Test This line indicates that it is message number 5 and the > indicates that the "current message pointer" is pointing to this message. The next two positions indicate the message status. The first may be one of, "N" (new and unread), "U" (old, but still unread), "*" (deleted), "S" (saved), "P" (preserved), or " " (read). The second position may have an "r" if the message has been replied to. The author of the example message header is argv@spam.istc.sri.com, the date is Feb 19, the number of lines in the message is 10, the number of characters is 278 and the subject of the message is Test. The format of the message header shown here is described by the string variable hdr_format. The example given above has a hdr_format of set hdr_format = "%25f %7d (%l/%c) %25s" See the description of hdr_format in the VARIABLES section for more information on header formats. You can print a special subset of message headers by using the -H:c option, where `c' is one of: a all messages d deleted messages n new messages o old messages r replied to messages s saved messages u unread messages Note that the -H is not required; "headers :c" is valid. More options to the headers command include `+' and `-'. Each will print the next or previous screenful of message headers. The z command can also be used; `z' alone will print the next screenful (thus, the `+' is optional) and "z -" is equivalent to "h -". Page 33 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Headers affects all the messages it displays, so piping may be done from the headers command. Piping to the headers command causes the message headers affected by the previous command to be printed. This action is identical to piping to the from command. help [topic] Help is provided on a per topic basis and on a general basis. For general help, just typing help will provide some general information as to how to get further help and a list of topics suggested for more specific help. There is also help provided for each command by using the -? option to most commands. This option will provide command line usage information as well as a description of what the command does and how to use it. If no help file is found, an error message will be printed. The location of the help files may be reset by setting the variables cmd_help and tool_help to the paths of the new help files. The tool_help variable is recognized only by versions capable of using suntool mode (tool mode need not be active). history [-h] [-r] [N] This command displays the command history in chronological order; early commands are printed first followed by more recent commands displayed last. Option -h suppresses printing of history event numbers with each history command. Option -r reverses the order of the history events displayed. If a number N is given, then that number of previous commands is echoed rather than the number set by the variable history. See the LINE-MODE INTERFACE section for a description of referencing the history in commands. ignore/unignore [header-list] Display or set a list of headers to be ignored when displaying messages. When reading messages, all the message headers are displayed with the text body of the message. Since these message identifier fields are cumbersome and uninteresting in many cases, you can filter out unwanted headers by using this command. For example, ignore Received Date Message-Id will ignore the three specified fields. Additional Page 34 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) ignore commands are cumulative. The command unignore is used to reverse the effects of ignore. For another way to control this, see the variable show_hdrs. lpr [-h] [-n] [-Pname] [msg-list] Takes a message list and sends those messages, one by one, to the printer, each separated by page feeds. The -h option suppresses printing of ignored headers (see the ignore command and the variables show_hdrs and alwaysignore), and the -n option suppresses all headers. A default printer name is supplied if one is not specified on the command line (-Pprinter-name). If you have the variable printer set, that printer name will be used. If the variable print_cmd is set, the command described by that variable will be used instead of the default system command. In such cases, the -P option and the printer variable are ignored and the command is simply executed as is. The "printed" status bit is set for each message printed by this command. ls [flags] This command duplicates the UNIX(TM) command /bin/ls. By default, ls always uses the -C flag (columnate output). mail [flags] [recipient ...] (m) Send mail to a list of users. If no recipient list is specified on the Mush command line, then a "To: " prompt will request one. A list of recipients must be supplied at some time before the message is sent, but is not required to begin composing a letter. This implementation of Mush supports mailing to files and programs as recipients. Filenames must be full pathnames; thus, they must start with a `/' or there is no way to know whether a recipient is a pathname or a user name. The special characters `+' and `~' may precede pathnames since they are expanded first to the user's folder directory (+), as described by the variable folder, and the user's home directory (~). Mailing to programs is indicated by the pipe `|' character preceding the program name. Since the user's path is searched, full pathnames are not required for programs that lie in the user's PATH environment variable. Example: Page 35 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) mail username, /path/to/filename, "|program_name", +folder_name, ~user/mbox Options are: -b addr-list set list of blind carbon recipients -c addr-list set list of carbon copy recipients -E edit outgoing message headers -e immediately enter editor (autoedit) -F add random fortune to the end of message -f [msg-list] forward messages (not indented) -H file read file as prepared text (no headers) -h file read file as a draft (text and headers) -I [msg-list] include messages with headers (indented) -i [msg-list] include messages in letter (indented) -s [subject] prompt for subject [set subject explicitly] -U send draft immediately (use only with -h) -u unsigned: no signatures or fortunes added -v verbose (passed to mail delivery program) The verbose option may not be available depending on the mail transport agent on your system. The -e flag causes you to enter the editor described by the variable visual. The -E flag causes Mush to place the headers of the outgoing message in the editor file so they can be changed. See the description of the variable edit_hdrs for details. The -i flag will include the current message into the body of the message you are about to send. The included message is indented by the string "> " or by the string described by the variables indent_str, pre_indent_str, and post_indent_str. See the VARIABLES section for more information on these string values. If a message list is given after the -i option, then the messages described by that list are included. The -I option is identical to the -i option except that the headers of the message are also included. The -s flag looks at the next argument and sets the subject to that string. If the string is to contain spaces, enclose the entire subject in quotes. If there is no following argument, then the subject will be prompted for. This flag is useful if the user: +o does not have the variable ask set, or +o wishes to change the subject used with reply The subject is not prompted for and is ignored completely if the -f flag is specified (see below). Page 36 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) The -f flag is for message forwarding only. An optional message list can be given just as the -i option has. The forward option does not allow you to edit the message(s) being forwarded unless the -e flag is also specified. The subject of the message (if available) is the same as the current message; it is not necessarily the subject of the message being forwarded. The subject of forwarded mail cannot be changed. However, using the -e flag will allow the user to change the subject once in editing mode either by using the escape sequence, "~s", or by editing the "Subject:" header. Forwarded mail that has not been edited by the user will contain special headers such as Resent-To: Resent-From: and perhaps others, depending on your mail transport agent. Sendmail, for example, may add a number of other "Resent-*" headers. The -u option, meaning "unsigned", prevents signatures and fortunes from being appended to the message. It overrides the variables autosign and fortune, but will affect the -F option only if given after it on the command line. The -h option indicates that the given file is a previously prepared message, possibly a partial one saved with "~w". Such a file is called a draft. The file argument must be given, and in the current implementation all message headers must either be present in the file or must be added manually by the user. At minimum, there must be a "To:" header; Mush will add "From:" and "Date:" headers when sending, if necessary. To read a prepared text file that does not contain headers, use -H. If the -U option is also given, then the letter is sent immediately without further editing. map[!] [string [expansion]] unmap[!] string The map command creates or lists macros for the line mode interface, and the map! command creates or lists macros for the message composition mode. In either mode, macros act in such a way that, when string is typed, the effect is the same as if expansion had been typed instead. The string is usually one or two control characters, or a sequence sent by one of the Page 37 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) "function keys" of a particular terminal. See the MACROS section for the syntax used to specify the string and the expansion, and for comments on the interactions of macros in the same and in different modes. If no arguments are given, these commands will display the list of macros and expansions for the appropriate mode. If only a string is given, they will display the expansion associated with that string for the appropriate mode. Otherwise, they will create a macro, associating the given expansion with the specified string. Line mode macros are unset with the unmap command, and composition mode macros are unset with the unmap! command. merge [-N] folder-name Messages from the named folder are read into the current folder. The header summaries of the merged messages are printed unless the -N option is given (see the folder command, above). This command can only appear in a pipeline if it is the first command; it returns a list of all the messages from the merged-in folder. This command cannot be used in initialization files before the shell has started. my_hdr/un_hdr [header] You can create personalized headers in your outgoing mail using this command. Command usage: my_hdr print all your headers my_hdr header print value of header my_hdr header: string set header to string un_hdr header: unset header To set a header, the first argument must be a string that contains no whitespace (spaces or tabs) and must end with a colon (:). The rest of the command line is taken to be the text associated with the mail header specified. If any quotes are used in the header and the header itself is not set in quotes, then quotes should be escaped (preceded) by a backslash. This holds true for semicolons, pipe characters or any other metacharacter that Mush might interpret as a command line modifier. If the variable no_hdrs is set, then your headers will not be added to outgoing messages, but no headers will be unset. The un_hdr command may take `*' as an Page 38 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) argument to un_hdr everything set. Example: my_hdr Phone-Number: (415) 499-8649 Mush treats the the header "From:" as a special case. If you have set your own From:, a simple test is performed to determine whether the address given is valid. Any UUCP or domain address that directs mail to your login at the local machine should be acceptable, but certain configurations may prevent some combinations from being recognized. If the address is valid, your From: header will be used; otherwise, an address known to be valid will be generated and used instead. Some mail transport agents are "picky" and will not allow Mush to supply a From: header; in these cases, your From: header is silently removed at send time, and replaced with one generated by the MTA. Note: You cannot set the "Date:". Attempting to do so will not result in any error messages; your date will simply be overwritten by the system when your mail is sent. pick [flags] [<pattern>] Allows the user to select particular messages from a folder. The <pattern> is a "regular expression" as described by ed. If no arguments are given, the previous expression searched for is used. You can search for messages from a user, for a particular subject line, between certain dates, and limit searches to a range of messages. You can also find all messages that do not match the same arguments mentioned above. Options: +<num> keep only the first <num> messages matched (head). -<num> keep only the last <num> messages matched (tail). -ago <format> search for messages relative to today's date. -d [+|-]date messages sent on or [+ after] [`-' before] date. -e take all remaining arguments to be the pattern. -f search for pattern in "From" field only. -h header search for pattern in specified header only. -i ignore case of letters when searching. -r msg-list search only the listed messages. -s search for pattern in "Subject" field only. -t search for pattern in "To" field only. -x select messages that do not match the pattern. The -ago option can be abbreviated as -a. Only one of -a, -d, -f, -h, -s and -t can be specified at once. Entire messages are scanned for the <pattern> unless Page 39 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) -a, -d, -f, -h, -s or -t is specified. Messages marked for deletion are also searched. No patterns can be specified with the -a or -d options. The -x option may not be used in conjunction with +n (head) and -n (tail). For the -d option, "date" is of the form: month/day/year with an optional `-' to specify that the messages of interest are those older than that date. Omitted fields of the date default to today's values. Examples of selecting on date: pick -d 4/20 on April 20, this year. pick -d -/2/85 on or before the 2nd, this month, 1985. pick -d +5/4 on or after May 4 of this year. pick -d / today only. At least one `/' char must be used in a date. There is no strong date checking; 2/30 would be considered a valid date. For the -ago option, the format is very simple. Specify the number of days followed by the word "days", or the number of weeks followed by the word "weeks", and so on with months and years. Truncation is allowed, since only the first character is examined, so all of the following are equivalent: pick -ago 1 day, 2 weeks pick -ago 2Weeks 1Day pick -ago 2w,1day pick -a 2w1d These examples will find all messages that are exactly 2 weeks and 1 day old. All "ago" dates collapse into "day" time segments. This means that months are 30.5 days long. If more precise date selection is required, use the -d option and specify specific dates. Also note that the -ago option allows the "before" (-) and "after" (+) arguments. Thus, you may pick all messages older than 1 week with: pick -ago -1 week Other examples of pick: pick -d 2/5/86 | pick -d -2/5/87 | pick -s "mail stuff" | lpr Page 40 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Will find all the messages between the dates February 5, 1986, and February 5, 1987, that contain the subject "mail stuff" and send them to the printer. pick -s Re: | delete Deletes messages that have "Re:" in the Subject header. folder +project | pick -f frank Finds all messages from frank in the folder described by +project. pick -h return-path ucbvax Searches all messages that have the header "Return- Path:" and determines if the string "ucbvax" is in the header. Note that case sensitivity applies only to the pattern searched, not the header itself. pick -ago +1w | save +current This finds all messages that are a week or less old and saves them in the file called current, which is found in the user's folder variable. pick +3 mush-users Finds the first three messages containing the string "mush-users". eval -h "pick +2 -r .-$ -s %s" | pick -1 Finds the next message with the same subject as the current message. pipe [-p pattern] [msg-list] unix-command Allows the user to send the texts of a list of messages to a UNIX(TM) command. The list of messages may either be given explicitly or may come from a Mush pipeline (see "Piping commands" under the LINE-MODE INTERFACE section). If a list is neither given nor piped, the current message is used. All headers are considered part of the message text for purposes of this command unless the value of the variable alwaysignore includes the word "pipe" (see alwaysignore in the VARIABLES section for more information). For example, pipe 3 5 7 patch sends the text and headers of messages 3, 5 and 7 to the patch utility. Page 41 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) If a pattern is specified with the -p option, Mush will search the message for a line beginning with that string. The matching line and all succeeding lines will be sent to the unix-command. If -p is not given, and the unix-command is omitted, Mush will search for a line beginning with "#!" and feed that line and all succeeding lines to "/bin/sh". Thus, pipe with no arguments treats the current message as a shell script. The pattern may also be of the form /pattern1/,/pattern2/ in which case printing will begin with the line containing pattern1 and end with the line containing pattern2 (inclusive). Patterns of this form must still match at beginning of line, and regular expressions are not currently allowed. The pipe command can also be invoked as Pipe (note capitalization), in which case only the body of the messages, and none of the message headers, are sent to the unix command. When the variable unix is set, UNIX(TM) commands can appear anywhere except as the first command in a Mush pipeline without explicitly using pipe. However, it is still necessary to specify Pipe in order to exclude all headers. Note: All messages listed as arguments to pipe or Pipe are sent to the standard input of the same process as a continuous stream! This is probably not desirable when extracting shell scripts in particular, so take care. Future revisions may provide an option to control this behavior. preserve (pre) Saves a message list in your spool directory rather than your mailbox unless it has been explicitly deleted. The variable hold causes all messages to be held in your spool directory automatically. print (p, type, t) Takes a message list and displays each message on the user's terminal. If the first letter of the command is a capital letter (`P' or `T') then "ignored" headers are not ignored provided that the variable alwaysignore is either not set or is set to one of its possible values. If this variable is set with no value, the ignored headers will be ignored regardless of the command used to display the message. See the ignore command for more information about ignored message headers. Page 42 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) The `+' and the `-' keys can be used to display the "next" and "previous" messages respectively. The `+' key has the caveat that the message is not paged at all and none of the messages headers are displayed. pwd Prints the current working directory. quit (q) Updates the current folder and exits from Mush. If the variable "hold" is set, all messages not marked for deletion are saved in the spool directory. Otherwise, messages that have been read are saved to ~/mbox or to the file described by the string variable mbox. Messages marked for deletion are discarded. Unread messages go back to the spool directory in all cases. reply/replyall [msg-list] [-r path] [flags] [users] (r/R) Messages are replied to by sending mail to the sender of each message in the given message list. The command replysender is equivalent to reply. Replyall responds to all the recipients as well as the sender of the message. These commands understand all the same flags as the mail command. When constructing a return mail address to the author of a message, reply searches for special mail headers in the author's message that indicate the most efficient mail path for return mail. Mush will search for the "Reply-To:", "Return-Path:", and "From:" headers, in that order, by default. If none of these fields are found in the message, the first line of the message is parsed if possible; this "From " line is different from the "From: " line. If the user wishes to change the order or the actual fields to search for return paths, then the variable reply_to_hdr may be set to a list of headers to be used (in the order specified). If it is set, but has no value, the first "From " line is used regardless of what headers the author's message contains. The "From " line may be specified explicitly as an item in the list of reply-to headers by specifying the header: From_. See the VARIABLES section for more information about reply_to_hdr. When replying to all recipients of the message using the replyall (R) command, only the original author's address can be obtained from the message headers. There is no way to determine the best path to the other recipients of the message from message headers aside from taking their addresses directly from the "To:" and "Cc:" lines. Page 43 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Example: replyall 3,4,5 -i 4,5 7 -s response mail-group Here, messages 3, 4 and 5 are replied to (all the authors are obtained from each of those messages as well as the recipients from those messages) and the text from messages 4, 5 and 7 are included in the body of the reply. The subject is set to "response" and the alias mail-group is appended to the list of recipients for this message. The -r flag will prepend the path to each recipient in the address list with the indicated path. This overrides the value of auto_route, but has the exact same functionality. See the explanation of the variable in the VARIABLES section. Also see the MAIL ADDRESSES section for more information concerning replying to messages. save/write/copy [-f] [-s | -a] [msg-list] [filename / directory] (s/w) With no arguments, save and write will save the current message to the file mbox in the user's home directory (or the file specified by the mbox variable). If a message list is given, then the messages specified by the list are saved. If a filename is given, then that filename is used instead of mbox. The -s options forces the filename used to be that of the subject of the message. Similarly, the -a option causes the filename used to be that of the author of the message being saved. If more than one message is being saved, the subject or author name used is that of the smallest message number (since message lists have no order of precedence). With these two options, a directory name may be given to specify a directory other than the current directory. If the file exists and is writable, the specified command will append each message to the end of the file. If -f is given, then the file is overwritten causing whatever contents it contains to be lost. For compatibility with older versions, the character `!' may be substituted for -f (no `-' is used with `!'). If the current folder is the system mailbox, then saved messages are marked for deletion when the user exits using the quit command. If the variable keepsave is set or the current folder is not the system mailbox, then messages are not marked for deletion. The write command differs from save and copy in that the message headers are not saved in the file along with the body of text. The copy command is is like Page 44 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) save except that messages are never marked for deletion, whether or not keepsave is set. Because message lists are used to determine the messages to be saved, if the user wishes to save messages to a file that begins with a digit or any other message list metacharacter, a backslash should precede the filename to escape the message list expansion routine. The backslash will not become a part of the filename. saveopts [file] The complement of source, saveopts, will save all settable variables, aliases and cmd's in the initialization file. (See the INITIALIZATION section for more information on initialization files.) If an argument is given, that file is used. Beware that this will overwrite files, so any "if" expressions will be lost, as will settings that have changed since entering Mush. Using saveopts is highly discouraged and is intended for the naive user only. set [[?]variable [= value]] unset variable With no arguments, set prints all variable values. Otherwise, it sets the named variable. Arguments are of the form "variable=value" (whitespace is allowed). Boolean options such as autoedit need not have "=value" associated in the command. Multivalued variables are set in the same way as other variables, and the list of values should be enclosed in quotes if whitespace is used to separate the items. See the VARIABLES section for details of the format of each type of variable. The special command set ?all will print all known variables utilized by the program and a brief description of what they do. The user may set and manipulate his own set of variables, but internal variables that are utilized by the program are the only ones displayed. The command set ?variable_name will print the same information for one variable instead of all variables. You may unset everything by issuing the command "unset *". Page 45 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) It is possible to set a variable to a list of messages returned by another command by using the piping mechanism. For example, pick -s Status Reports | set reports The variable reports now contains a message list which can be used as the message list argument to any command which accepts a list. mail -i $reports boss This command will mail to "boss" and include the text of all the messages held in the reports variable. sh [command] Invokes an interactive version of the shell. The shell spawned is described by the variable shell. If the optional argument command is given, then that command is executed under the Bourne Shell. If the special character `&' is at the end of any shell command, then the command will be executed in background. source [file] Read Mush commands from a file. If no filename is specified, the files searched for are .mushrc or .mailrc in the user's home directory. If the environment variable MUSHRC or MAILRC is set, then the file named by the variable is sourced instead. If a filename is given on the command line, that file is sourced. See the INITIALIZATION heading and the home variable descriptions for more information. sort [-i] [[-r] -a | -d | -l | -R | -s | -S] This command will sort messages according to author, date, status or subject (with or without considering the "Re: ", in replied messages). In addition, the messages can be sorted in reverse order (same arguments). Options: -i ignore case in alphabetical sorts -r reverse sort order of next option -a sort by author (alphabetical) -d sort by date -l sort by length of message -R sort by subject including "Re:" -s sort by subject (alphabetical) -S sort by message status By default (no arguments), sort sorts messages by status. New, unread messages are first, followed by Page 46 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) preserved messages, and finally deleted messages are placed at the end of the list. If -r is the only option given, the status ordering is reversed. When sorting by date, the boolean variable date_received is checked. If it is set, then sorting goes by date received. Otherwise (default), sorting is by date sent by the original author. If more than one sort option is specified, they will be applied in left-to-right sequence to each comparison. Thus: sort -a -d sorts messages by author and, if the author of any set of messages is the same, sorts within that set by date. Note that the -r option applies to only one other option at a time; to reverse the sort of both author and date requires: sort -r -a -r -d The options can also be grouped: sort -ra -rd sort -rard Currently, only the line mode interface supports multiple sort criteria, but the other interfaces allow subsorting indirectly when appropriate actions are taken, as discussed below. It is also possible to sort a consecutive sublist of messages by using pipes. If the mailbox were already sorted by author, pick -f argv@zipcode.com | sort -s would find all messages from the user "argv@zipcode.com" and sort them by subject. You may specify the exact message list by specifying that message list on the command line and using a pipe: 10-. | sort d This command means to sort the messages from 10 to the current message according to the date. To specify subsorting from with the curses interface, the temporary curses escape key must be used (the colon `:') and the command issued at the `:' prompt (as if Page 47 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) giving an "ex" command to "vi"). When the command is finished, the "...continue..." prompt is given and the user may continue or return to the top level of the curses mode. The sort range must consist of consecutive messages. Reversed sorting is not currently available in tool mode. If the variable sort is set, messages are sorted each time the user's system mailbox is read as the current folder. The sort variable can be set either to nothing or to legal "sort" arguments. Note: For compatibility with older versions, sort options are recognized even if they are not preceded by a `-'. Also, if a `-' is given by itself (separated by spaces from any following arguments) it is interpreted as -r. stop For systems with job control, stop will cause Mush to send a SIGTSTP to itself. The command was introduced to facilitate the stop-job action from a complex command line alias rather than the user having to type his stop character explicitly. top Takes a message list and prints the top few lines of each. The number of lines printed is controlled by the variable toplines and defaults to the size of the value of the variable crt. This command is ignored in the tool mode. undigest [-m] [-p pattern] [msg-list] [filename] A "digest" is a mail message which is a collection of other mail messages mailed to a "moderator" by other users. The moderator compiles all the messages into a folder and sends the result to all the subscribers of the mailing list. The undigest command disassembles the entries into the set of messages which comprises the digest. The -m option will merge these messages into the current folder. Otherwise, if a filename is specified, a new folder is created and the user can change folders to read the messages separately. The -p option specifies an alternate pattern to be used as the digest article separator. This pattern must match literally at the beginning of the line. The default pattern is "--------" (eight hyphens). This is the defacto USENET standard digest article separator and should work for most digests, but some use another Page 48 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) separator. The -p option is also useful for "bursting" forwarded messages out of a wrapper message; for example: undigest -m -p "--- Forward" will burst out messages forwarded by another user of Mush and merge them into the current folder. If a message list is specified, each digest in the list is disassembled to the same filename (if given). If no filename is given and the user did not request a merge, then a temporary file is made. update [-r] Updates your current folder, writing back changes just as if you quit. Headers are not listed when the folder is read back in. The -r option puts the folder into read-only mode after updating it. See the folder command for complete information. VARIABLES Shell variables are controlled via the set and unset commands. Options may be either boolean, in which case it is only significant to see whether or not they are set; string, in which case the actual value is of interest; numerical, in which case the numerical value is important; or multivalued, in which case they may be set to a list of values. Some variables may have attributes of boolean and string or multivalued at the same time. If you or the program references a variable that is not explicitly set, then the environment variables are checked and that data is returned. Variable values can be modified by one of four variable modifiers, or by a numeric string. The modifiers `:h', `:t', `:l' and `:u' may be applied to the variable names. The current implementation allows only one `:' modifier on each `$' expansion. :t The variable is treated as a file path name, and the name of the file (the "tail" of the path) is substituted for the variable. That is, everything to the right of the last `/' is returned. :h The variable is treated as a path name, and the "head" of the pathname is substituted for the variable. That is, everything up to, but not including, the last `/' is returned. Page 49 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) :l All alphabetic characters in the variable's value are converted to lower case. :u All alphabetic characters in the variable's value are converted to upper case. :number The value of the variable is converted to a list of space-separated words, which are numbered from one (1), and the word described by number is selected and returned. It is not an error for number to be greater than the actual number of words; an empty string is returned in this case. Following is a list of all variables with predefined meanings. alwaysignore (Boolean/Multivalued) If set with no value, the mail headers set by the ignore command are always ignored. Normally, ignored headers are not ignored when sending messages to the printer, when interpolating messages into letters with ~f or ~I, when the `P' or `T' command is given (see the print command), or with the -I flag to the mail or reply commands. Setting alwaysignore will ignore those headers even in the situations mentioned here. No headers can be ignored during updates and when using the save command since the user may ignore headers that are required by Mush or any other mail system to read those folders. This variable can also be set to a list of words separated by commas or spaces. Currently recognized words, and their meanings, are: forward Ignore headers when forwarding messages (~f). include Ignore headers when including messages (~I). pipe The pipe command ignores headers. printer The lpr command ignores headers. Also see the ignore command and the show_hdrs variable for more information. ask (Boolean) If set, you will be prompted for a subject header for outgoing mail. Use the tilde escape "~s" to set the header once in the message or specify the -s option on the mail command line at the Mush prompt. askcc (Boolean) If set, you will be prompted for a Cc (carbon copy) list when you are finished editing a letter to be sent. If the variable edit_hdrs is set, prompting will not occur, but a Cc: line will be added to the edit Page 50 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) file. This also applies to the tool mode. autodelete (Boolean) When exiting mail, all messages that have been read regardless of whether they have been marked for deletion are removed. Only messages that haven't been read or that have been marked as preserved are not removed. autoedit (Boolean) If set, you are automatically put into your editor whenever you send or reply to mail. autoinclude (Boolean) When replying to any mail, a copy of the message being replied to is automatically inserted into your message body indented by the string described by the variable indent_str. autoprint (Boolean) After you delete a message, the next message is printed automatically. auto_route (Boolean/String) If set boolean (not to a string), all the recipients in a message that is being replied to (via replyall), will be routed through the path back to the original author. For example, if the original sender of a message came from the remote host c3p0 and the list of recipients looked like From: c3p0!user1 To: yourhost!you Cc: r2d2!user2, r2d2!user3 then clearly, "user1" on the machine c3p0 can talk to your machine and the machine named r2d2. However, you would not be able to respond to those users if your machine did not exchange UUCP mail with the host r2d2. Mush will attempt to solve this problem by reconstructing the addresses for "user2" and "user3" according to the address of the original sender, "c3p0". The new addresses for "user2" and "user3" should therefore become c3p0!r2d2!user2, c3p0!r2d2!user3. If your machine not only talks to c3p0, but talks to r2d2 as well, it becomes unnecessary to route the mail Page 51 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) through both c3p0 and r2d2. So, the variable known_hosts may be set to a list of hosts which you know your machine to have UUCP mail connections with. This list is checked when constructing mail addresses for replies only and the shortest path is made by removing from the UUCP path those hosts that do not need to be called or are redundant. See the entry for known_hosts for more information. If auto_route is set to a specific pathname (host names separated by !'s), all addresses in the reply will have this route prepended to their addresses. This ignores the original path of the author. This is quite useful for hosts which talk uucp to a node which is connected to the internet or uunet since both of those machines tend to be one-hop away from all other hosts (or reroute accordingly). For example, if a message was addressed like so: To: root@ucbvax.berkeley.edu, argv@zipcode.uucp Cc: ucbcad!foo!bar If auto_route were set to "ucbcad", then replies to this address would be directed addressed like so: To: ucbcad!ucbvax.berkeley.edu!root, ucbcad!zipcode.uucp!argv Cc: ucbcad!foo!bar This assumes that the host in question talks uucp with ucbcad. This example demonstrates several things. First, notice that all addresses are converted to uucp-style format. Whenever routing is changed, the format is converted like this. Secondly, note that the Cc: line did not change. This is because all redundant hostnames from UUCP pathnames are removed to avoid unnecessary UUCP connections and speed up mail delivery. Another example of how auto_route truncates UUCP paths: pixar!island!sun!island!argv Here, mail was probably originally sent to users at pixar and sun from somewhere undetermined now. Since sun and pixar do not talk to each other, the users on those machines may have responded to mail creating the type of addresses stated above. Here, it can be seen that we can reduce the path to the host island: pixar!island!argv Page 52 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) See the MAIL ADDRESSES section for more detailed information about legal mail addresses. Note that the -r flag to reply and replyall overrides the value of auto_route. autosign (Boolean/string) Append a signature to outgoing mail. If this variable is set, but not to a string (e.g., boolean-true) then the file ~/.signature is used. Otherwise, the variable is interpreted in one of four ways. By default, the string is interpreted as a pathname relative to the current directory. For this reason, it is advisable to use full pathnames here. As usual, the special characters `~' and `+' are expanded. If a file is found, it is opened and its contents are read into the message buffer. If the variable is set to a string that begins with `$', then that string is interpreted as a user- definable variable and is expanded and appended to the letter. If the variable is set to a string that begins with a backslash (\) then the string itself (minus the `\' character) is used; no expansion is done and no files are read. Finally, if the variable is set to a string that begins with a vertical bar (or "pipe") character (|), the rest of the string is interpreted as a command whose output will be used as the signature. The special characters `~' and `+' are NOT expanded in the command name, but the command is run via /bin/sh so $PATH will be searched and redirection can be specified. The list of addresses to which the letter will be sent is passed to the command as its arguments, in the same form that they will be passed to the Mail Transport Agent (MTA). Depending on your MTA, each address may be followed by a comma. In the latter three cases, it is advisable to set the variable using single quotes to protect the `$', `\' and `|' characters from being interpreted. Examples: set autosign = '$foo' set autosign = '\ Dan Heller zipcode!argv@ucbcad.berkeley.edu' Warning: if redirection from the calling shell is used, no signature or fortune will be added to outgoing mail. For example, Page 53 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) % mush -s report manager < report_file In this command, mail is being sent to the user "manager" and the subject is set to "report" and the file "report_file" is being redirected as input. In this case, there will be no signature appended. Note: The `|' syntax for calling a program to sign the letter is a little counterintuitive and may change in future releases. autosign2 (String) This alternate signature is available for special cases where the default signature is not desired or if no signature is desired for special addresses or if only special addresses require a signature. The format for this variable is: autosign2 = "address1, address2, ... : <signature>" Each address can be one of these types: 1) address Legal mailing addresses that do not contain comment fields (see the sections MAIL ADDRESSES for more information on legitimate mail addresses) will match literally. 2) *username If the username is present on the recipient list, regardless of what remote site the user may reside on (including locally), the pattern matches. 3) !hostname !host1!host2... Any user who appears as a recipient will match the pattern provided he resides on the specified hostname. If a path of hosts is specified, then the user must reside on the last host of the specified path. 4) @sub.domain The user must reside on any host within the domain specified. Neither the user or the hostname needs to match; only the domain name must be required to match. Example: set autosign2 = "!zipcode @sun.com @mit.edu *schaefer root: --dan" This means that any mail sent to 1) anyone at zipcode, 2) anyone within the sun domain, 3) anyone within the Page 54 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) mit domain, 4) Bart Schaefer (at any host anywhere -- even locally), and 4) root on the local machine only (or, root@local-machine-name) will be signed with the "alternate" signature. If any address on the recipient list fails to satisfy these four matches, the mail will be signed by my regular signature. One can have a local signature and a remote signature by specifying the autosign2 to include the hostname of the home machine the user is logged into. Note the "zipcode" example above. The list of recipients, after alias expansion and comment removal, is then scanned and the following patterns are matched against those addresses specified in the autosign2 or fortunates variable according to these rules. The signature description is the same as described by autosign variable. The colon (:) separates the list of addresses from the signature description. If there is no colon or the address list is missing, the entire string is considered the signature (except for the colon). If autosign is not set, then autosign2 will ONLY work if the tilde command "~S" is specified. In this way, a user may never have autosign set and just set autosign2 to be some signature value. The user may then issue the tilde command to automatically sign the letter. If a list of addresses is given (terminated by a colon), then all recipients of the message must be in the list of addresses in autosign2; otherwise, the signature in autosign (if set) is used instead. A null signature in autosign2 will not sign the letter. Example: set autosign2 = "fred, barney, wilma, betty: ~/flintstone.sig" If a message is sent to: To: fred, wilma Then the file ~/flintstone.sig will be used. However, if the address were: To: barney, betty, bambam Then autosign2 will not be used because bambam is not in the list. Page 55 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Note that mail sent via redirection from the calling shell will not sign letters or append fortunes. cdpath (String) Set to a string of pathnames separated by spaces to use when searching for a directory when the cd command is issued. If this variable is used, it is recommended that the path `.' be included. Note that this differs from the csh, which does not require that `.' be present. cmd_help (String) This variable gives the path name of the general help file, which is read by the help command. This variable is normally reset only in the system initialization files, when the default location of the help file has changed. complete (String) Setting this variable enables word completion. The first character of the value of complete is used as the completion character; if complete is set, but not to a value, the escape character is used as the default. When the completion character is typed at the end of a word prefix, Mush will interactively complete that word. If the prefix is not unique, the word will be completed as far as possible and a bell will sound (see, however, the variable quiet). If the word contains filename metacharacters, all possible matches will be completed. If the list overflows the command line buffer, it will be truncated, so this feature should be used with care. Metacharacters recognized are the same as in csh. The second character of the value of complete is used as the completion listing character. When this character is typed, the possible completions will be printed, and Mush will prompt again with the original prefix. If complete is set to only a single character, completion listing is disabled; if it is set with no value, control-D (^D) is used as the default listing character. See the description of the variable fignore for ways to exclude filenames from completions. Word completion is currently supported only for file names. Command name and alias completion may be added in a future version. Completion is not possible if the -e (-echo) flag was given, and is currently not available in tool mode. Page 56 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) crt (Numeric) Set to a value that describes the number of lines a message must have before invoking the pager to view a message. crt_win (Numeric) Set to the height (in lines) of the message display window in tool mode. curses_help (String) This variable may be set to a space-separated list of curses mode command names (see the CURSES section for the possible choices). If set but without a value, a default list established by your Mush maintainer is used. When it is set, a display of the current bindings for the listed commands will appear at the bottom of the screen in curses mode. This help display will normally shorten the display of headers, but the the user may explicitly scroll over the help display if he wishes to see more headers. cwd (String) The current working directory string is automatically set upon startup of Mush and is reset each time the commands cd and pwd are called. It may be changed or referenced like any other shell variable. date_received (Boolean) When message headers are printed, the date is normally shown is the time and date the sender sent the message. If this variable is set, then the date displayed is the date received. When sorting messages by date, this variable is queried to determine whether the messages should be sorted by date sent or date received. Warning: For mailers that store messages without a line that starts with "From ", this option does nothing. dead (String) File to use instead of dead.letter when interrupted mail is saved. May be set to a unix command by prefixing the value with `|'. For more information, see the variable nosave. domain_route (Boolean/String) In combination with auto_route, this variable specifies that addresses containing a fully- qualified domain should be short-circuited to mail directly to the rightmost fully-qualified domain. If set boolean (not to a string), only short-circuiting is done. If set to a string, the address is rewritten to UUCP form and the value of the variable is prepended. Domain short-circuiting applies only to addresses Page 57 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) containing a fully-qualified domain, but short-circuits in spite of any path specified with the -r flag of reply or through the string value of auto_route (thus possibly omitting the auto_route or -r paths altogether). See auto_route for more information. dot (Boolean) Causes Mush to accept a `.' on a line by itself, in addition to `^D', to terminate messages. editor (String) Specifies the editor to use when the "~e" escape or the edit command is used. Default is the value of the environment string EDITOR or the variable visual. edit_hdrs (Boolean) When in letter-composition mode (via mail or reply, etc), the headers of the outgoing message are stored in the same buffer as the text of the letter. So, if the editor is called to edit the message buffer, the headers of the message can be edited as well. However, there are some restrictions. There must be a To: header. Without this, Mush will not deliver the letter. Instead, the editor must be reentered and a To: header with a valid recipient must be inserted. A valid Cc: header does not remove this restriction. You may have as many To: and Cc: headers as you like. The From: header normally should not be changed. If you change this header to an address that Mush is unable to identify as authentic, the original From: header will silently be put back. The Date: header will always be replaced by one with a more accurate time and date stamp. Therefore, changing or removing this header has no effect. You cannot add a Status: header, and blank headers are dropped. For example, if an empty Cc: header exists, the header will not show up in the outgoing message. Therefore, leaving empty headers has no effect. Aliases specified on the command line are expanded and put into the message buffer in their expanded form regardless of the value of no_expand. However, if the user changes the headers using the editor and specifies aliases, those aliases will not be expanded if no_expand is set. Otherwise, they are expanded as usual. Page 58 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) The headers Bcc: and Fcc: are removed as expected. One added side effect of edit_hdrs is that you can add an Fcc: header to specify a "File Carbon Copy". This must be a pathname to a file or program. For programs, the pathname must be preceded by a pipe character (|). Note that all addresses on the Fcc: line that do not begin with `|' are interpreted as file names; don't put other kinds of addresses there. When using edit_hdrs, certain tilde escapes don't work. Specifically, any tilde escape that allows you to add or set headers or to empty the file are inactive. These functions are to be done in the editor only. Once a letter is being edited, edit_hdrs cannot be set or unset; the user must end the letter (either by sending it or forcefully terminating it) first. Header editing is required (and happens automatically) when using the "Compose" tool mode item. escape (Character) When composing a mail message (not in an editor), and the escape character is the first character on the line, the next character is examined and a corresponding function associated with that escape command is executed. See tilde escapes for more information. fignore (String) This variable is tested when filename completion is used (see the variable complete for details). The value of fignore may be a list of filename extensions (".c", ".o", etc.), a list of filename patterns containing metacharacters (*?{}[]), or a mixture of the two. Each element in the list must be separated from the others by a space. When a filename completion occurs, any filenames with the extensions listed in fignore, or matching the patterns given there, will be omitted from the completion. For example, set fignore = ".o .s [Mm]ake*" will cause any filename ending in ".o" or ".s", and any filename beginning with "Make" or "make", to be excluded from completions. If all files in the current directory match the extensions or patterns, fignore is disabled and Page 59 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) completion will occur. For this reason, it is usually not a good idea to include "*" in the list. folder (String) The folder variable is set to the path of a directory where folders are kept. This path is used by various commands to expand the `+' metacharacter (see the folder command for details). "~/Mail" is the default expansion of `+'. fortune (Boolean/string) If fortune is set, a random fortune is appended to the end of all outgoing mail using the UNIX(TM) command /usr/games/fortune (may vary from system to system). If fortune is set to something that starts with a `-', then it is interpreted as a flag to fortune (e.g., "-o"). If fortune starts with a `/', then the program described by the string is executed (thus not doing fortune at all, if you want). By default, fortune -s (short fortunes) is used. fortunates (String) When fortunes are added to messages, sometimes it is desirable to make sure that only a selected group of people get a fortune since certain people may not understand the messages at the end of your mail. Therefore, you can set a list of addresses (either pure addresses or aliases that are expanded to addresses) to be the only people who receive fortunes if one is to be appended. Therefore, if the To: and Cc: lines contain only address listed in this string variable, then a fortune is appended to the message. If those lists contain names that are not on the fortunates list, then no fortune is added. This cannot be overridden; using the tilde command "~F" does not force a fortune to be added unless the individuals on the recipient list are all included in the fortunates list. The list is made up of addresses or aliases separated by spaces or commas. NOTE: fortune must be set in order for fortunates to work. hangup (Boolean) If this variable is set, Mush will update your folder before exiting when it receives a SIGHUP signal. This is useful if you frequently read mail when dialed in over a noisy phone line that often drops carrier. WARNING: Certain errors are ignored during this update, because it is presumed to be impossible to query the user for instructions. Except in the event of a write error, the folder will be forced to contain Page 60 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) exactly those messages that were not deleted at the time of the hangup. In particular, this means that if an error occurs when loading new mail before the update, the new mail will be lost. Write errors will still cause both the working tempfile and as much of the folder as possible to be preserved. hdr_format (String) This variable controls the format of the headers displayed by the headers command and in the curses and tool modes. The format style of this variable string is similar to printf in C. When printing the information, the variable is evaluated and each character in the string is echoed unless a `%' character is encountered. If one is found, the following string substitutions are made: %a address of the author %c number of characters (bytes) in the message %f entire "From:" field (author) %l number of lines in the message %i the message-id (may not be present) %n name of the author %s subject of the message %t "To:" field (recipients) %d date and time of the message %T time only of the message %N day number of the month of the message %W day of the week (Sun, Mon, etc.) %M month name of the message %Y year of the message %y last two digits of %Y %Z time zone of the message \n a newline \t a tab A field width specifier may be used in all options. Thus, "%20f" will print the first 20 characters of the from line. No matter what the formatting string, the message number followed by a `>' (for current message) is printed. The "address" and "name" of the author are extracted from the "From:" field of the message. The name may be given in parentheses and the rest of the line is the address, or the address is given in angle brackets (`<' and `>') and the rest of the line is the name. Sometimes the address is the only thing on the line, in which case the name and address are the same. A special format is also provided to obtain the contents of any header not listed above. If a format Page 61 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) of the form "%?header-name?" (both leading and following `?' characters are required) appears in the value of hdr_format, the named header will be looked up. For example, set hdr_format = "%a %n %?phone?" causes the electronic address, name, and (if a "Phone:" header is present) phone number of the sender to be displayed. history (Numeric) This variable is set to the number of commands the shell interface will remember. It is just like the history variable used in csh. If unset, the last command can always be referenced, but none other. hold (Boolean) Normally, on termination of mail, read messages are saved in your mbox (except those marked as preserved). Setting hold prevents this from happening, and messages remain in /usr/spool/mail/user. This does not apply to folders, obviously. home (String) This variable describes the user's home directory. The variable is initialized to the value of the environment variable HOME, but can be modified at any time during the Mush session. The home directory is the same directory where temporary files are kept for editing and so forth. If the home directory cannot be found or read/write access is denied, an alternate directory, typically /tmp, is used. hostname (String) This is the name of your computer. Currently, its sole usage is to compose a correct "From:" line for use with Mail Transport Agents that do not create this header automatically. This will aid the recipients of your mail in replying to your messages. Note: the user should not have to set this variable since it should be set automatically by the system. However, it may happen that the system's hostname cannot be queried and the user may have to set this variable manually. ignore_bang (Boolean) If set, Mush will ignore the `!' character as a history reference. Note that this severely limits use of the cmd facility, which depends upon history references for argument substitutions. ignoreeof Page 62 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) (Boolean/string) If set, `^D' will not exit from Mush. If set to a string, that string is executed as a command when `^D' is typed. This does not effect termination of messages under the mail and reply commands. indent_str (String) When including messages into the text of a letter you are editing, each line of the messages is preceded by the value of indent_str. If it is unset, the message body is indented by the string "> ". See also the variables pre_indent_str and post_indent_str. in_reply_to (String) This variable may be set to a string that will complete the header "In-Reply-To:". The format of this string is identical to the options for the variable hdr_format. For example, if the user were to respond to a message from Dan Heller that was sent on October 21, 1987, at 10:39pm, with in_reply_to set to the string %n's message as of %d. the header line In-Reply-To: Dan Heller's message as of Oct 21, 1987, 10:39pm. would be added to the message. keepsave (Boolean) If set, the commands save and write will not mark messages for deletion. known_hosts (String) Used in conjunction with the variable auto_route, this variable is set to a list of hosts, separated by spaces, tabs, and/or commas, and describes the hosts with whom you know your machine shares UUCP connections. When replying to mail, many times you will see that the return path constructed will have hostnames that your site could call, but instead the mail has been routed through a number of different machines first. For example, if you respond to mail that would mail to the path unicom!pixar!root but your know your machine already calls pixar, then Page 63 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) sending the mail to unicom first is unnecessary. If you have set your known_hosts string to include pixar in its list, the resulting address would look like pixar!root Also see the command replyall for more information on constructing correct return addresses. logfile (String) Set to a filename which logs the headers of outgoing messages. The message body of the message is not logged as it is for the record filename. The logfile can be read as a folder to scan for the fact that messages have been sent. If logfile and record are both set, then the logfile and the record files will match exactly. In this case, the record file can be quickly scanned by scanning the log file instead. If set, but not to a string, the log file defaults to ~/mail.log. mail_icon (String) Set to a pathname for an alternate icon pixmap to use when the Mush tool is closed. The number of messages in the mailbox is displayed as an icon label unless the string iconlabel appears as one of the values of the variable quiet. See also the variable newmail_icon for the icon displayed when new mail arrives or is present. mbox (String) Set to the pathname of a file you'd like Mush to use as the default folder for read mail. The default is ~/mbox. metoo (Boolean) When replying to mail, you are normally deleted from the list of recipients. If metoo is set, you remain on the list. See the alternates command for information on determining whether or not you're even on the list. mil_time (Boolean) Whenever the time is displayed in a message header or in the prompt, it can be displayed in either 12-hour am/pm format, or in 24 hour military time format. The default is the 12 hour format, but can be reset to use the 24 hour format by setting this variable. newline (Boolean/string) If set, carriage returns are ignored. Page 64 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) If set to a string, that string is executed as a command when a carriage return is typed. Otherwise, carriage return prints the next undeleted message. newmail_icon (String) Set to a pathname for an alternate icon pixmap to use when new mail is available. no_expand (Boolean) When a Mush alias is used to reference a list of addresses, the list is expanded on the To: and Cc: lines to indicate the complete list of all the recipients of the message. When no_expand is set, aliases are not expanded and the headers reflect the same information as typed by the user. no_hdrs (Boolean) If set, this variable tells Mush not to include your personalized mail headers in messages. This does not unset your headers, it just disables them. no_reverse (Boolean) In curses mode and in the tool mode, reverse video is not used to indicate the current message if this variable is set. In the tool mode, if reverse video is not in use, text is displayed in "bold". nonobang (Boolean) If this variable is set, history references that don't match anything will be left unexpanded, rather than generating error messages. This is useful if you want argument referencing in cmd expansions, but do not want to remember to escape every `!' you type in UUCP addresses. It is also recommended for use with curses mode, because history is not kept for line mode escapes from that interface. nosave (Boolean) When composing a letter, the user can terminate the letter without sending it by using the tilde escape "~q" or by sending two "interrupt" signals. When the message is terminated, a copy of it is saved to the file "dead.letter" in the user's home directory or to the file described by the variable dead. If the variable nosave is set, then a backup copy of the message will not be saved. output (Read-only string) This variable holds a message list representing the output of the last successful command. This is useful for recovering from broken pipes or to capture the output of a command without affecting the Page 65 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) information it displays (some commands limit or suppress output when used in a pipeline). Commands which return an error status (see the variable status) do not affect the value of output, but successful commands that return no message list will clear it. Also, many curses mode commands return an error status to indicate that the display has been altered, even if no actual error occurred. This variable is thus most useful in line mode and in scripts. pager (String) If a message is longer than the number of lines that the variable crt is set to, then this program is executed to view a message. If the user does not have this variable set, the user's environment PAGER is checked. If this isn't set, then the default value for pager (set up by the system manager) is used. This may or may not be the internal pager. To use the internal pager, you may set the variable pager to internal or to a null string. pre_indent_str (String) If this variable is set, when including the body of a message into an outgoing mail message (using the -i option to reply or mail, or when using the "~i" escape), a line preceding the first line of included text is printed using the string value of the variable. This string uses the same printf style formatting characters as the hdr_format variable. For example, you could set pre_indent_str as follows: set pre_indent_str = '[In the message entitled "%s", on %7d\n %n writes:]' You can then include a message body using "~i", and you might get something like this: [In the message entitled "This is a test.", on Jan 19, Dan Heller writes:] > This is a test message to show how > pre_indent_str might be used. This example assumes that the string value of indent_str is not set. post_indent_str (String) This variable has the same function as pre_indent_str except that the string is inserted into the message body after the text of the included message rather than before. The purpose of this variable is to complement the string described by the variables pre_indent_str and indent_str. For example, Page 66 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) set pre_indent_str = "/*" set indent_str = " * " set post_indent_str = " */" An included message might look something like this: /* * This is a test message to show how * post_indent_str and pre_indent_str * can work together with indent_str. */ printer (String) Used to set the default printer for the lpr command. print_cmd (String) This string should describe a UNIX(TM) command other than "lpr" for sending messages to the line printer. Some people may choose to use a device independent troff style program, but virtually any UNIX command will suffice. Common usage might include: set print_cmd = 'ptroff -ms -Plp' lpr .-$ This command would send all messages from the current message to the last message through the ptroff command, supplying the appropriate arguments. prompt (String) You can set your prompt to tell you many different pieces of information. By default, the prompt is set to the string "Msg %m of %t: " If you have 10 messages and your current message is 5, then your prompt would look like: Msg 5 of 10: The string value that prompt is set to will be printed as your prompt. If the string contains a `%', then that character is ignored, the next character is evaluated and an appropriate value is printed in its place: %F full path name of the current folder %f name of the current folder (tail of %F) %m "current message" number %t total number of messages Page 67 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) %n number of "new" messages %u number of unread messages %d number of deleted messages %T current time (hours and seconds) %N today's date (Number of the day in the month) %W weekday name (Sun, Mon, Tue, ...) %M current month %Y this year %y last two digits of %Y \n a newline \t a tab quiet (Boolean/Multivalued) This variable tells Mush to be quiet in various circumstances. If set, but not to any values, the currently running version of Mush is not printed on startup. Otherwise, quiet may be set to one or more words separated by spaces or commas. Currently recognized words are: autosign Suppress messages when appending signature. await Suppress await's bell for new mail. complete Suppress word completion error bells. fkey Suppress warnings about unset function keys. fortune Suppress messages when appending fortune. iconlabel Suppress showing message count as icon label. newmail Suppress new mail notification messages. pick Suppress descriptions of pick searches. startup Suppress the startup message. tool Suppress tool mode bell for new mail. Error conditions for signatures and fortunes are still reported. See the variables autosign, complete, and fortune for more details. The newmail setting does not prevent automatic inclusion of new mail, it only suppresses the announcement of its arrival, including tool mode bells. The fkey setting applies only to tool mode. realname (String) Set to the name of the user. The name is initialized to the value of the environment variable NAME upon invocation of the program. If that isn't set, then the name is gotten from the password file if available. If this variable wants to be reset or changed after the program has started, the user should issue the command: set realname = "Your name here" record (String) Set to the name of a file to record all Page 68 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) outgoing mail. This should be a full pathname or the current directory is searched. The pathname may begin with `+' (indicating the user's ~/Mail directory or the value of the folder variable) or with a `~' (or "~user") indicating the user's home directory. reply_to_hdr (String) When replying to mail, Mush searches for return paths from the message by searching for the message headings "Reply-to", "Return-path", and "From:", in that order. If none are found, then the first line of the message created by the delivery system is parsed and the address given there is used. This special message header is created by most mail delivery programs, but not all of them (MMDF, for one). This line is called the From_ header because it is a colon-less header, but contains the return address of the author of the message. If the variable reply_to_hdr is set to a list of headers (delimited by spaces or commas), then that list is searched. If none of the headers listed in the variable exist in the message, then a warning message is printed and the default headers are used. The special case From_ header can be specified as one of the headers to search for. set reply_to_hdr = "sender reply-to return-path from_" This example shows that Mush will search for (in order), the headers listed in the reply_to_hdr variable. If one header isn't found, then Mush looks for the next in the list. If none of the headers in the list are found, the default headers (mentioned above) are searched. The last header listed in the example is the special "From " header. Also see the reply command. save_empty (Boolean) Normally, when all messages in a folder are deleted and the user updates the folder or changes to a new folder, the empty folder is deleted. save_empty prevents the folder from being deleted and it is left zero length. Note: the main system mailbox is never deleted, even when empty. screen (Numeric) May be set to the number of message headers to display at a time in the line and curses modes. screen_win (Numeric) May be set to the number of message headers to display in the tool mode. A subwindow is created Page 69 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) for message headers, and its size is large enough to hold $screen_win headers. sendmail (String) If set, the program and arguments described by this variable will be executed to actually deliver mail sent by Mush. show_deleted (Boolean) If true, deleted message headers are displayed along with other messages (`*' indicates a deleted message) for the headers command. Also, deleted messages can be displayed using any command which displays a message. In curses mode, this variable is ignored and deleted messages are always displayed with other messages to facilitate undeleting messages. show_hdrs (Multivalued) Set to a list (space and/or comma separated) of headers that are to be the only headers displayed when viewing a message. This variable disables the headers suppressed by the ignore command. For example, set show_hdrs = "from date subject to cc" will only display the headers From: Date: Subject: To: Cc: in their entirety. sort (Boolean/string) The value of this variable is the same as the arguments to the sort command. This variable is used for the initialization file to presort mail in the system mailbox upon entering Mush. See the COMMANDS section for more information. squeeze (Boolean) Whenever messages are read, piped, or saved, if this variable is set, all consecutive blank lines are squeezed into one blank line. status (Read-only numeric) This variable records the success or failure status of the most recently executed command. All line-mode commands return 0 (zero) for success and a negative value for error. Some curses mode commands return an error status to indicate that the display has been corrupted, even when no actual error has occurred. This variable is most useful in scripts to test the success of an operation before proceeding. Page 70 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) tmpdir (String) This variable describes the path to use as the directory for all tempfiles that Mush uses. By default, the user's home directory is used. If that cannot be accessed, a directory writable by all is used (typically, /tmp). If tmpdir is set, then it is used first. thisfolder (Read-only string) The full path name of the current mailbox. This variable cannot be modified or displayed by the set command; its value changes whenever a new folder is entered with the folder command. During sourcing of the initialization files, thisfolder is not set, because the current folder has not yet been read. If you refer to "$thisfolder" in an initialization file (e.g., .mushrc), be sure to do so inside an "if $?thisfolder" test. toplines (Numeric) The number of lines of a message to print when the top command is issued. If unset, $crt lines are printed. Note that the message body only is printed when using the top command; message headers are not counted as lines since they are not displayed. unix (Boolean) If set, commands that are not Mush commands are considered to be UNIX(TM) commands. This removes the inconvenience of requiring the user to do shell escapes to do quick UNIX commands. For systems that support job control, SIGTSTP will stop the entire shell as well as the process being executed. When SIGCONT is delivered, both will receive the signal and the shell will continue to wait for the job to finish. Due to the lack of real job control, input/output redirection and UNIX command piping, this mode of the shell is not intended to be used as a login shell. If a Mush command conflicts with a UNIX command, use the command sh to force execution as a shell command or use the full pathname of the command (e.g. starting with a '/'). Warning: Be aware that Mush pipes transmit message lists, NOT TEXT. You cannot pipe the output of UNIX commands to or from Mush commands or other UNIX commands with the Mush pipe mechanism. You can, however, pipe Mush commands to a final UNIX command (see the pipe command for more information). UNIX commands should be simple commands without pipes or metacharacters. Page 71 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) This feature is not available for the tool mode. verbose (Boolean) Passes verbose flag to mail delivery systems when sending mail, and causes Mush to print additional information about the sending process. verify (Boolean) When through editing messages, just before sending, verify will ask you if you want to send, continue editing, or abort the whole message altogether. version (Read-only String) The value of this variable is the version string, printed by Mush at startup (unless quiet is set) and included in the "X-Mailer:" header in messages. visual (String) May be set to the visual editor to use when ~v is specified. Default is vi or the environment string VISUAL. The visual editor is invoked by the -e arguments to the commands, respond and mail. warning (Boolean) If set, warning messages are printed when: +o A command line alias ("cmd") looks like a command. For example, cmd mail 'set fortune; \mail' cmd respond 'unset fortune; \respond;' +o The date format of a message is unknown. The date of a message is taken from the "Date:" header. If the date on that header is unknown, other headers are searched for a valid date format until a legal one is found. This date may not be correct in that it was the date the message was received, not sent. +o A variable is unset without first being set. For example, if you give the command unset metoo and the variable metoo is not set, you will be notified that the variable is not defined. +o No header can be found for a digest article. This occurs when the undigest command encounters what appears to be an article separator but cannot find a "From:" or "Date:" header in the following text. The intent is so that users who are used to their own environments will be aware of changes in other environments should they be forced to use them. There Page 72 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) may also be warning messages of failed routines or assertions that are not fatal enough to interrupt normal running of the program. wrap (Boolean) Normally, when the last message is deleted, the current message pointer remains pointing to the last message and the user is done reviewing his mail. If the wrap variable is set, the current message pointer will wrap around to the beginning of the user's messages again to the next undeleted message. This also applies to the next command. wrapcolumn (Numeric) May be set to a column number at which line wrap will occur when composing messages. If set, but given no value, column 78 will be assumed. When Mush is able to determine the number of columns on your screen, it will enforce a maximum value for wrapcolumn of two less than that number of columns. Line wrapping can be disabled either by unsetting wrapcolumn or by setting it with the explicit value of 0 (zero). Line wrapping occurs only at whitespace (spaces or tabs). Lines containing no whitespace to the left of the specified column will not be wrapped. If Mush was started with the -e (echo mode) option, or is in tool mode, line wrapping cannot be done due to I/O incompatibilities. In addition to the named variables described above, three special variable forms are recognized. $$ This string returns the process id (PID) of the current mush process. Colon modifiers are not recognized for this special variable. $[%fmt] The string %fmt is interpreted as a header formatting string (as in the hdr_format variable) and is expanded using the headers from the current message. Colon modifiers are allowed to follow the format. For example, save $[%4n]:l will save the current message in a file whose name is the first four characters of the name of the author, converted to lower case. $(%c) The string `%c' is interpreted as a prompt format (as in the prompt variable) and is expanded. Colon Page 73 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) modifiers are allowed. For example, echo $(%T) will print the current time. Note that "$(%F)" is equivalent to "$thisfolder". NOTE: Evaluation of many "$[%...]" or "$(%...)" values in a single command is inefficient. If expansion of several formats is desired, it is better to use the -h and -p options of echo or eval, which also provide better quoting of the interpolated strings. MUSH SCRIPTS One of the most useful features of Mush is the ability to write scripts of commands, which can be read by the source command from within Mush, or by redirecting input from the script and using the -i option. If your operating system supports the "#!" interpreter mechanism, a script can be even be executed as a program. Script files can use all the usual Mush commands; the only restriction is that the `!' history notation for referencing arguments of cmd aliases is disabled in scripts, so only very simple cmds will work. For example, a filtering file, "filter", might contain: set newfolder = /usr/spool/mail/$USER if is_shell if -z $newfolder set newfolder = $mbox # mbox must be set! endif if -e $newfolder folder $newfolder else quit endif endif pick -f Mailer-Daemon | save mail_errors pick -f yukko | delete pick -s -i thesis | save +thesis_mail pick -t unix-wizards | +wizmail update sort d Then the first command the user types when beginning a Mush session might be "source filter", and the following would happen: First, a new variable called newfolder is set to the the user's spool mailbox (the system mailbox). A test is made to see if the shell is running, because the folder command Page 74 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) can only be used from the shell. Then a test is done to see the spool mailbox is zero length, and if it is, the variable is reset to the value of the user's mbox variable (mbox must already be set by this time or this will fail). A final test assures that the new folder exists. If it does, Mush changes folders to the new folder. If it doesn't exist, the program exits (via quit). Once the correct folder has been loaded, all messages that have "Mailer-Daemon" in the From header will be saved in the file mail_errors. Then, all mail from the user "yukko" will simply be deleted. Next, all mail that has in the Subject field, "thesis" (case ignored, so "Thesis" would also match) will be saved in the file $folder/thesis. The next command will find all messages that are addressed to the group "unix-wizards" (of which the user is an elite member) and save them in the file $folder/wizmail. Last, the folder will be updated, removing all deleted mail (saved mail may be marked as deleted) and the folder is reread and sorted according to the date of the messages. If the "#!" mechanism is supported, the "filter" script can be made into a program by adding as the first line: #! /usr/local/bin/mush -F (The actual location of mush may vary from system to system; /usr/local/bin is used as an example.) Then make the file executable: chmod +x filter Now, when the command "filter" is typed at the user's regular shell prompt, the mush program will be invoked by the operating system. Mush will first read the commands from the "filter" file and perform them, exactly as described above, and then will continue into the usual interface. If it would be preferable for mush to exit after reading the script, the first line can be changed to: #! /usr/local/bin/mush -F! The -F! option should also be used when running scripts in the background or in other circumstances where the standard input cannot be a terminal, and the only commands to be executed are those in the script itself. Note that any additional arguments passed to a "#!" script are interpreted by mush; they are not passed along in any way that makes them accessible to the script. Thus, Page 75 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) % filter -f mbox would apply the commands in the "filter" script to the "mbox" folder. MACROS Macros are available in several different modes in Mush. Curses mode macros are created by using the bind command with the special function macro (or by using bind-macro, which is synonymous). These macros are effective only when the curses interface is active. Line mode macros are created with the map command, and are effective only in the line-oriented command interface. Finally, composition mode macros are created with the map! command, and are effective only when composing mail messages. Macros are not available in the tool mode, nor when composing messages from the tool mode. Line and composition mode macros are also nonfunctional when Mush is started with the -e (echo) option. In general, macros consist of two parts: a key sequence and an expansion. The key sequence is the character or string of characters which, when typed in the appropriate mode, is recognized by Mush as a reference to a macro. The expansion part of a macro is the string that will actually be "seen" by Mush when the key sequence is recognized. Macros are like an interactive search-and-replace function; if a key sequence appears in the input, the associated expansion is substituted in its place. Thus, if you create a macro whose key sequence is "^X^W" (control-X control-W) and whose expansion is "save", then when you hold down the control key and type the two characters `x' and `w', the effect will be as if you had actually typed the four characters `s', `a', `v' and `e'. This is called "expanding" the macro. More detailed examples of macros will be presented in the subsections for each mode in which macros can be used. Key sequences are usually made up of control characters or special strings of characters generated by "function keys," but may in fact be almost any string the user desires. Keys that generate a signal or an end-of-file from the keyboard (for example, on BSD systems, control-Z generates a TSTP signal and control-D generates an end-of-file) can never appear in key sequences, and macros in line or composition modes cannot begin with a newline, control-D, or any of the editing keys (erase, word-erase, line-erase, etc.). Otherwise, there are no restrictions. It should be kept in mind, however, that for the line and composition modes, key sequences should be unusual characters or combinations of characters, not individual lower-case letters. If common characters or strings are used for key sequences, much confusion can result when typing commands or messages. This Page 76 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) is not important in the curses mode. In the line and composition modes, a timeout is used for key recognition; that is, once the first character of the key sequence has been typed, the succeeding characters must be typed after it relatively quickly, or Mush will fail to recognize them as a continuous sequence. It is for this reason that key sequences are usually either very short, or are strings that are automatically generated by pressing a special key on the terminal. On the other hand, the timeout can be used intentionally to prevent a macro from being expanded; simply type the first character of the macro, then wait for it to echo before typing the next. This does not work in curses mode, because curses macros never "time out." In any mode, macros are recursive; that is, if the key sequence of one macro appears in the expansion of another macro (or even of the same macro), the second key sequence will be recognized when the first macro is expanded, and this new key sequence will also be expanded. Great care should be taken when creating macros to be certain that recursive expansions do not happen unintentionally. Expansion can be prevented in line or composition modes by using a literal-next character. Literal-next characters may be used from the keyboard or embedded in expansions. In either case, they prevent the next character from being interpreted as part of a key sequence. Mush recognizes the literal-next character from the tty settings of the terminal, if the "new" BSD-style device driver is available; otherwise, `^V' (control-V) is recognized as a literal-next. Note that, if you have a tty literal-next character, then when typing you will need to type two of them in order to send one to Mush; this is because the tty driver consumes the first one. It is not necessary to use two literal-nexts in macro expansions unless you wish to cause the second literal-next to be literal. Backslash can be used as a literal-next when typing, and can sometimes be used as a literal-next in expansions; but use it with caution, because it also introduces escape sequences (see "Macro syntax," below). There is no literal-next mechanism for curses mode. A macro will always abort whenever any command called by the macro returns an error. This includes recursive expansions, so no matter how often a macro has recurred, it will be terminated completely. Errors in curses mode include illegal cursor movements, such as up from the top of the screen or down from the last message. Page 77 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Macro syntax. A special syntax is provided for specifying control characters and other non-printing characters in macro key sequences and expansions. This syntax is the same as that for bindings, discussed in the CURSES INTERFACE section; it can be summarized as: \CX control-X (where X is any capital letter) \E the escape character \n a newline (other C-style escapes also work) Thus, to create a line mode macro for control-X control-W, as in the example above, the command would be map '\CX\CW' save Also provided is a syntax for executing functions from within macros. There are two special functions that are effective in all modes; these are getstr and getline. Both of these functions interrupt expansion of the current macro, and wait for a newline-terminated string to be entered from the standard input. This input string is inserted into the macro expansion. The functions differ in that getline retains the newline character (carriage-return) at the end of the input string, whereas getstr strips off the newline (one must still be typed to terminate input). These functions can be executed by surrounding their name with square brackets ([, ]); for example, map '\CX\CW' save [getline] creates a line mode macro, which is expanded when control-X control-W is typed, and which displays "save" followed by a space and then waits for the user to type a line of input; the input line will be used as the arguments to the save command. Additional functions are currently available only in the curses mode. However, the syntax of enclosing the function name in square brackets applies to all functions, regardless of mode. Note that ONLY the function name can appear in the brackets; no whitespace is allowed. Curses mode macros. Macros in curses mode are the most versatile, because they can access the full range of curses commands quickly and easily. Every character that appears in the expansion part of a curses mode macro can reference a curses command or another macro. Like other curses functions, curses mode macros are created with the bind command. For example, to sort your messages by date and then send the most recent one Page 78 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) to the printer, you could use bind @ macro 'od$|' When the `@' key is typed, this macro first invokes sort (`o' from the default bindings) and instructs it to use date (d) for sorting; it then moves the current-message pointer to the last message ($) and prints that message (|). Admittedly, the above macro is somewhat cryptic, and is dependent upon the bindings for sort, last-msg, and lpr being set to the defaults. It would be better, and possibly more understandable, to refer to the desired curses functions without using their key bindings. To allow this, the "[function]" syntax described above may be used in curses mode macros to reference curses functions. The only function that is prohibited from appearing in the "[]" is the special macro function, which cannot be called when it has no binding. The example macro can therefore be rewritten as bind @ macro [sort]d[last-msg][lpr] Such references to curses functions may be made only in curses mode macros, and are effective only when Mush is actually in curses mode. That may sound strange, but the most common use of curses macros is to quickly perform functions that require an escape to the line mode. For example, although there is a variation of the curses mode mail function that will prompt for additional flags, there is no function to prompt for flags to be passed to reply. A macro can easily be created to provide this: bind R macro '[line-mode]reply ' This macro binds `R' to perform an escape to line mode and type the string "reply" followed by a space. Macro expansion then ends, leaving it up to the user to supply flags to the command or to backspace over it if a different command (or none) is desired. Of course, the macro could also have provided some default arguments: bind R macro '[line-mode]reply -ei ' Note that, if the getline or getstr function is used in a line-mode escape, it is not possible to erase the text that is typed before the get; that is, if the macro had been bind R macro '[line-mode]reply -ei [getline]' then the user would be forced to use the -ei flags. Page 79 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) Line mode macros. Line mode macros combine some of the convenience of single- keystroke commands with the versatility of the line-oriented text interface. As has been noted, the choice of characters for line mode key sequences should be made carefully, so as not to interfere with normal typing. Line mode macros are created with the map command; for example, suppose you frequently forward messages to a friend named "fred." You could create a macro to do this: map '\CF' 'mail -f . fred\n' This macro causes the single keystroke `^F' (control-F) to forward the current message to "fred." Note the newline character "\n" at the end of the expansion; this causes the command to be executed immediately, without you having to type a carriage-return. The expansion part of a line mode macro will echo to the screen when it is expanded, so you can see what the macro is doing. You can therefore use parts of the expansion as a "prompt." In the above example, suppose you wished to enter a message list rather than always forwarding the current message. Change the macro to: map '\CF' 'mail -f [getstr] fred\n' This version of the macro prints "mail -f" and a space, then waits for a newline-terminated string from the standard input. The newline is stripped, and the string is used as the message list passed to the "mail -f" command. The address "fred" is also passed to mail, so the messages in the list are forwarded to fred. If you want to be able to "change your mind" after starting a line mode macro, you must leave the "\n" out of the expansion. Without the newline, the macro will not be executed immediately, so you have a chance erase the line (or part of it) and type something different. Remember that the getline function keeps the newline in the string it gets, so if you don't want a newline to appear, you must use getstr. When using the get functions, you should also remember that you can never backspace past the "beginning" of a getline, and you can backspace past the beginning of a getstr only after the get has been completed. When the getstr function is used in line mode macros, Mush will reprint the current input line so you can see what the whole thing looks like, but will not redisplay the line mode prompt (see the entry for prompt in the VARIABLES section for information on what the prompt looks like). Don't let Page 80 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) this worry you. The input line is also reprinted when getline is used, but the newline in the input string usually results in a new prompt being displayed. NOTE: Line mode macros are not available when using the line-mode escape function in curses mode. It is necessary to escape all the way to line mode (that is, leave curses mode by typing carriage-return at the `:' prompt) in order to access line mode macros. This is to prevent possible confusion when similar macros exist in both line and curses modes. Composition mode macros. Composition mode macros are very similar to line mode macros, and provide a "power typing" function when composing messages. For example, you might want to have the word "percent" inserted into your message whenever you hit the `%' key: map! % percent Another use is to simulate the indentation features of editors. For example, you might map! '\CT' ' ' (where the expansion is four spaces, enclosed in single quotes). This macro causes four spaces to be inserted into the message whenever control-T is typed. Composition mode macros can also be used to execute tilde- escapes (see the GENERAL USAGE section for a list of these). For example, you could create a macro to invoke the editor: map! '\CE' '\n~v\n' When control-E is typed, this macro prints a newline (to be sure that the tilde-escape is the first thing on a line), then types "~v" followed by another newline, to start the editor. Similar macros can be created for other tilde- escapes. Mixed mode macros. It is not normally possible to mix macros among the different modes. However, once expansion has begun, it is interrupted only by an error or by the appearance of one of the special get functions. It is therefore possible to have a macro expansion which causes the mode to change before the expansion has completed. In this case, recursive expansions will apply to the new mode. Suppose we are using a Page 81 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) variation of the editor-starting macro shown above for composition mode: map! '\CE' '\n~v emacs\n' This macro causes the "emacs" editor to be started when control-E is typed in composition mode. We can now create a line mode macro that makes use of this composition mode macro: map '#' 'reply -i [getline]~t[getline]\CE' When the `#' key is pressed in line mode, this macro will print "reply -i" and wait for a message list, then enter composition mode (by executing the reply command). In composition mode, it will display the To: line (the "~t" escape) and wait for other addresses to be added. Finally, it will recursively expand the control-E macro, to start editing the message with emacs. As can be seen from this example, the Mush macro facility is very powerful. Be very careful not to accidentally expand recursive macros, especially when using macros that change modes. When testing new macros, it is a good idea to start Mush in read-only mode (the -r command line flag) to be sure that messages are not lost or altered. Getting rid of macros. It is not necessary to delete a macro in order to redefine it. New expansions for existing key sequences will automatically replace the old expansions. If it is necessary to remove a macro completely, the commands unbind, unmap and unmap! can be used to remove curses mode, line mode, and composition mode macros, respectively. Remember to use a backslash or other literal-next character to prevent the expansion of line mode macros when using these commands, especially unmap. MAIL ADDRESSES Whenever a command that requires a user address or set of addresses is specified (mail, reply, alias, etc) the addresses given must be separated by commas. Most casual users specify addresses that contain no comments or whitespace. The simplest addresses are just the login names of the users you wish to send your message to: mail fred barney wilma betty In these cases, Mush can figure out that they are separate addresses and insert commas between addresses automatically. Page 82 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) To: fred, barney, wilma, betty Addresses may also contain `!', `@' and `%' characters which are used to separate hostnames and the final user name from each other. This is primarily used to mail to users on other machines. UUCP addresses are specified as host1!host2!user where there may be as many hosts as necessary to route the message to the recipient user. Here, the user's account is on "host2" and that machine is connected to "host1". Domain addresses (also called Arpanet, Internet, RFC822, and "fully qualified" addresses) are specified as user@host.domain user%host2.domain@host1 where "domain" is a domain name such as ".berkeley.edu" or ".com". As in the first example, the user is on "host2", but that machine talks to "host1". It is beyond the scope of this document to discuss in detail the ramifications of inter-network mailing. More information can be obtained through your system manager. Mush understands addresses containing a comment field. Comment fields do not affect the destination address of mail being sent. These fields are purely for human legibility and may be specified according to the following constraints: Anything within angle brackets is an address; whatever is outside of the address is considered a comment: Dan Heller <zipcode!argv@cad.berkeley.edu> Dan Heller <argv@zipcode.com> Anything that has parentheses is a comment; whatever is outside of the parentheses is considered the address: zipcode!argv (Dan Heller) argv@zipcode.com (Dan Heller) Double quotes (") are treated just like parentheses: "Dan Heller" zipcode!argv "Dan Heller" argv@zipcode.com If the comment is to contain a comma, the first case above may not be used; you must use either the parenthesis or double-quote cases. fred@flintstone.bed.rock (Fred Flintstone, Cave Man) Page 83 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) If the comment contains unbalanced quotes, unpredictable results may occur (Mush won't deliver the mail). Since the angle brackets have the highest precedence, quotes or parentheses may be used in conjunction with one another. Yabba Dabba Doo (Fred Flintstone) <fred> Scoobie "Doobie" Doo <scooby@shaggys.mystery.machine> Multiple addresses may appear on a line: argv@zipcode.com argv@garp.mit.edu dheller Because there is no indication of comments (parenthesis, angle bracket, or quotes), it is assumed that these are separate addresses and Mush will insert commas between these addresses accordingly. It is for this reason that the user is encouraged to explicitly insert commas between all mail addresses and not depend on the automation of comma insertion to correctly separate addresses from one another. Mail aliases may contain addresses of the form described above. alias george George Jetson <george@spacely.space.sprockets> alias jane Jane Jetson <jane@sky-high.appts> alias group george, jane You can mail using the alias as an address and it will be expanded accordingly. You cannot, however, reference an alias and specify a comment or another address at the same time. To: The Jetsons <group> The alias "group" will not be expanded because the angle brackets causes it to be considered as another address entirely. FILES /usr/spool/mail/* Directory for incoming mail ~/Mail Default folder directory ~/mbox File where old mail is saved ~/.mushrc File giving initial Mush commands ~/.mailrc Alternate initialization file ~/.edXXXXXXX Temporary for file for outgoing messages ~/.mushXXXXXX Temporary mail file (copy of current folder) Temporary files that are created by the program are always created with read/write access to the owner only; group and other permissions are never set. This is also true for the /usr/spool/mail/* files. All other files created by the Page 84 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) user via commands internal or external to the program have permissions set by the user's default umask. If the umask is reset within the program, the mask remains intact even after exiting. Remember to set the variable unix before attempting to set the umask value. If your system is using Sun Microsystem's NFS, take special note to read the manual page for mount(C). Filesystems mounted for read/write access should be mounted as "hard" NFS mounts or you may lose mailboxes during a timeout during a write or update. Filesystems that use RFS still have bugs to be ironed out in the way of owners and permissions concerning utime(2). SEE ALSO Mail(C), binmail(C), csh(C), aliases(5), mount(C), mailaddr(F), sendmail(?), printf(S), execl(S), umask(C), utime(S). AUTHOR The original Mush was written entirely by Dan Heller. Code to support macros, line wrapping, and a whole lot of other miscellaneous details, was written by Bart Schaefer, who gets his name in print because he updated and proofread this manual. Numerous others have supplied valuable suggestions and assorted bits and pieces. argv@sun.com zipcode!argv Installation on this system, plus Dos(TM) and OS/2(TM) port, by Mike O'Carroll <lmoc@ee.leeds.ac.uk> DISCLAIMERS Mush contains no UNIX(TM) sources and never has. It is also not a modified version of any other mail user agent. Similarities with any other mailer may have been designed for compatibility reasons. UNIX is a trademark of AT&T. The Flintstones and The Jetsons are trademarks of Hannah- Barbara Inc. BUGS The curses interface uses the curses library. The routines from the library that are used are the most basic and simple so as to avoid possible bugginess that different versions of UNIX might have. However, one unavoidable problem is the reverse video mode. Depending on your terminal, the termcap entry for it, and the version of curses you are running, the reverse video may make things worse than desired. In such Page 85 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) situations, the user should set the variable no_reverse to not get reverse video. `^R' may still be entered at runtime in the curses interface to toggle reverse video. Toggling from the curses mode to the line mode to get the full functionality of the shell/line mode is unfortunately necessary in order to maintain the display in a sensible manner and to keep the keystroke-command interface simple and "user friendly". Mostly, such escapes are only necessary for piping of commands and using the pick command. Macros are a big help with this. If the program is already running and the system [later] has to swap and there is no swap space left, there may be problems. One such problem is sending mail. If this happens, then sending mail will fail and a segmentation fault from the spawned/forked child may occur (unless the -v flag was given to mail). The unsent letter will not be removed from the editing file ($home/.edXXXXXX) and may be recovered. Many functions available to the line oriented mode (shell mode) are not available to the tool mode. For example, pick may not be directly accessed although experienced users may find that typing pick commands within single backquotes in the "Range:" panel item above the header window and then selecting a command that uses the the range will indeed pick messages. This is mostly for selecting the "delete range" item or the middle mouse button icon in the header panel. Version 6.5.6 was the last version designed to run under SunWindows, and is therefore the most recent version that will function under SunOS 2.x. The current version, 7.0, has been ported to SunView, and may have a completely new set of problems in addition to those described below. Also, some of those described below may have been eliminated, and remain in this discussion only for completeness. Shell escapes (of any kind) may be called only from the "pipe" command in the tool mode, should not be interactive, and should produce output only to a file. The reason for this is that there is no tty window in which to do input/output. Since the interactive function-key binding interface has gone away, it is unfortunately only possible to execute commands that have been pre-defined in the initialization file. Future revisions may correct these deficiencies. The function keys and their ability to work has been variable depending on the version of SunWindows/SunView your Sun Workstation has. From time to time, it works, but when it doesn't, it seems to be related to other user or system Page 86 (printed 12/21/90) MUSH(C) Version 7.1.0 (Apr 25, 1990) MUSH(C) definable dot-files or whatever. This of course means that the function keys are relatively untested in conjunction with SunView (SunOS later than 3.3). The default function key bindings have been eliminated to avoid collisions with SunView window system functions. Changing the value of the screen_win, crt_win, or msg_win variables after the tool is running simply has no effect. When using vi in the tool mode, the window is periodically one line "short." That is, scrolling is off by one line and you have to redraw the window (using "z." in vi) to get it in sync again. This problem remains in most SunView implementations, but does not seem to appear with the current default composition window size. When running on full filesystems, Mush may complain or not even run since it needs temporary space with which to work. Instead of finding new filesystems on its own, Mush leaves this task up to the user. The workaround is to set the variable tmpdir in the initialization file to be a writable place in a filesystem that has enough disk space. Most of the other known and documented bugs are in the supplied README files accompanying the source. The source is also an excellent place to look as many known bugs are documented in comments. A good way to track suspicious bugs is to use the debug command, but note that this command is very difficult to use in curses mode. Page 87 (printed 12/21/90)