SSH

NAME

SYNOPSIS

DESCRIPTION

If an instance of ssh is a login shell, it first executes commands found in the file /etc/.sshrc. It then checks for the existence of the file .second in the users home directory. If the file exists a password is read out of the file and the user is prompted for the password. Failure to enter the correct password results in the incorrect password and information about the aborted login attempt to be logged in the file .warning which is created if necessary. If successful the shell checks for the existence of the .warning file and determines how many bad login attempts have been made and notifies the user. Next it then begins to read commands from the .login file found in the users home directory, then it loads the saved history from the .hist file and finally reads commands from the .sshrc file, also found in the users home directory.

If it is the case that it is not a login shell, ssh executes the system login file /etc/.sshrc then executes the .sshrc file found in the users home directory. The .sshrc file in the users home directory may be skipped if the -f command line option is passed as an argument to ssh.

After successfully logging in, the shell begins to accept input from the user, prompting with a `>' (or `#' if the user is the superuser), unless the prompt was changed by the user in either their .login or .sshrc file.

The shell then begins to repeatedly input lines of text from the user. These lines are placed in the shells history and then broken up into words, which are parsed each in turn for aliases, variables, logical assignments, and wildcards. Finally the words are passed to the executor where it parses for redirections and pipes and then finally executes the command.

Finally, when the shell terminates, it reads commands out of the .logout file located in the users home directory. Upon executing all the logout commands the shell exits.

LEXICAL STRUCTURE

The shell splits input lines into words at spaces and tabs with the following exceptions. The characters `;', `&', `|', `<', `>', `(', `)' as well as the metacharacters `&&', `&!', `&=', `||', `|!', `|&', `|=', `>>', `>!', `>>!', `>&', `>>&', `>=', `>>=', `<<', `<<=', `$<', `!=', `<%' `<<%', `>%', `>!%', `>&%', `>>%', `>>!%', `>>&%' form single words. These parser metacharacters may be made part of of other words by escaping them with backslashs `\'.

In additions, strings enclosed in `'', '`', or '"', form a whole word. Characters enclosed in these strings, save newline and the `\' are not parsed for any other special meaning except inside of double quoted strings where variable expansion may take place. The `\' followed by one of the following characters is replaced by a non-printing character:

       \a Bell (Ascii 7)

       \b Backspace (Ascii 8)

       \t Tab (Ascii 9)

       \n Newline (Ascii 10)

       \f Form Feed (Ascii 11)

       \r Carriage return (Ascii 13)

       \e Escape (Ascii 27)

       \0xxx Octal escape

`\' may also be used to escape the string quote itself as well and in double-quoted strings to escape the special meaning of the `$' symbol.

Words placed inside of `(' and `)' lose their special meaning to the shell. This includes all redirection, piping, background, variable identifiers, logical assignments, and all other special symbols.

Finally, the `#' at the start of a word starts a comment, where everything following the `#' is ignored by the shell. If preceded by a `\' or enclosed in a string it is prevented it's special meaning.

COMMANDS

Simple commands are composed of a sequence of words, the first of which is the command to be executed. A pipeline is two or more simple commands separated by `|', `|!' or `|&' metacharacters to form a complex command. In pipelines, the output of the first command is redirected into the input of the next command and so on. Simple commands or complex commands may be separated by `;' to execute them each in succession.

Commands may also be separated by the metacharacters `&&' indicate to the shell that if the previous command executed correctly, then the second command is also executed, otherwise it is not. Commands separated by `||' indicate that if the previous command executed correctly, then the second command is not executed, otherwise it is.

Commands may also be terminated or separated by `&'or `&!' to prevent the shell from waiting for the command to terminate. Commands submitted in this fashion are said to be in the background , as opposed to foreground jobs which are waited on to complete and have control of the terminal.

JOBS

The shell keeps a table of all jobs that are currently running or stopped that the user has executed. This table is printed by use of the builtin command jobs. Each entry has the form:

[<job number>] (<PID>) <status>                <job name>

where <job number> is the logical number the shell assigns to the job. The job is referenced by this number for the process control commands bg, fg and stop. The <PID> is the system process ID of the job. <Status> is the status of the job, which indicates whether the job is running or stopped and if it is in the background or foreground. The <job name> is the command word (first word) of the job started.

Typing ^Z (control-Z) while running a foreground process usually sends the stop signal to that processes. When this happens the process is stopped and the shell indicates that the job is stopped and return the user to the command line where they may run other commands or manipulate other jobs. Stopped jobs may be manipulated with the fg, bg and stop commands to place them in the foreground or background.

A job made to run in the background with the `&' or `&!' metacharacters has its input and output redirected to `/dev/null', the null device, automatically if it does not already have preexisting input and output redirections. This is to insure that background jobs do not attempt to read from or write to the terminal while you are doing something else. This automatic redirection to `/dev/null' can be turned off by setting the nobgnull shell variable, however it is recommended that if you desire terminal input or output for background jobs, you explicitly specify such by redirecting the appropriate descriptors to or from `/dev/tty' which is a system construct to equate to your current tty (which is also given in the string variable tty ). Jobs spawned with `&!' are in addition dissociated from the terminal entirely and the shell will no longer keep track of these jobs. This allows the user to spawn a background job, then logout without having background jobs "hang on" to the tty, sometimes causing inconvenience to the next user.

COMMAND LINE INPUT

The shells input routines support some 20+ editing functions. None of these functions are automatically bound to keys however, and should be defined in the global startup file .sshrc in the /usr/etc directory. These functions can be added, changed or removed with the use of the key and unkey builtin commands. The available editing functions are described briefly below in the description of the builtin command key.

An example of defining an editing macro:

     key -f5 "\010"

This macro defines the backspace key (octal 010) as a delete previous character (function 5) editing function. More than one key sequence can be bound to the same function, thus several keys can be made to delete the previous character (the author likes to make the backspace and delete perform the same function because they are very near each other on his keyboard).

Those with function keypads (like most vt100 keyboards), may define keypad keys as macros for editing or to quickly type out large commands. An example of a key macro is assigning control-D to logout the user:

     key -r -c "\004" logout

This macro emulates the csh shells logout on EOF. The `-r' means to make the input routine act as if the return key has been pressed after the macro has been inserted onto the command line. The `-c' means to clear the command line before inserting the macro string. The "\004" is the key sequence to bind the macro string to (in this case ^D), and `logout' is the macro string.

The shells macro routines also support the concept of keypad levels and `gold keys'. Keypad levels can be thought of as a stack of keypads, each with their own macros and function bindings. The purpose of gold keys is to change the current keypad level when it is pressed. An example:

     key -l0 -g1 "\033OP"

     key -l1 -g0 "\033OP"

These make the vt100 PF1 key a gold key which toggles between keypad levels zero and one (level zero is the default). The `-ln' assigns the gold key to keypad level n and the `-gn' defines the key sequence as a gold key, that when pressed, sets the keypad to level n. The shell maintains a stack of 10 keypad levels (0-9).

STATUS REPORTING

The shell performs status reporting of changes in the state of a job in an asynchronous manner. If the shell itself does not have control of the terminal (therefore is waiting for a process to complete), the status of child processes will not be reported.

Should you attempt to logout of your shell while you have stopped jobs, you will be notified with the message `You have stopped jobs.' and will not logout. The shell will not alert you a second time however, allowing you to logout normally. Any stopped jobs present at logout will no doubt be killed.

SUBSTITUTIONS

The following describe the various substitutions of the input line performed by the shell and in the order that they occur.

COMMAND SUBSTITUTION

Commands enclosed in ``' are parsed and executed before any other substitutions are done on the command line. The output of these commands is placed back into the command line in place of the command string. The resulting command line is then subject to the remaining substitutions.

The output of these commands are normally broken up into words in an identical fashion as described above in the lexical structure, save that newlines and null words are discarded.

ALIAS SUBSTITUTION

After command substitution is performed, the command line is parsed into distinct commands, and the first word of each command is scanned to see if it corresponds to one of the aliases setup by the user. If a match is found, the command line is replaced entirely by the alias, placing arguments into the new command line where indicated by the alias. An alias contains switches, signified by a `%', that specify the argument placement desired for the alias. These switches are evaluated left to right, and place the words of the old command line (numbered from 0) into the new command line. When a word from the old command line is inserted into the new command line, it is said to have been used. The following is a list of the valid switches:

%n

Word n is placed here.

%n-m

Word n through m are placed here.

%-

All unused words are placed here.

%+

All previously used words are placed here.

%%

All words are placed here.

%#

Places the number of words here. Useful for use with the single line if-then to insure the correct number of words for an alias command.

Argument zero is ignored for switches `%-', `%+', and `%%'. These switches may be embedded in a word, and since this substitution is recursive, multiple switches embedded in a word will produce every possible combination of those words. Examples:

> alias x (secho %%.%%)
> x a b c #will yield:
> secho a.a a.b a.c b.a b.b b.c c.a c.b c.c

> alias user (ls ~%1-10)
> user aa bb cc # will yield:
> ls ~aa ~bb ~cc

If no matches are possible for the switch, then the word the switch appears in is removed from the new command line. By default, if no valid argument switches are contained in the alias, then all the words from the old command line (minus the command) are placed at the end of the resulting new command line. Alias parsing only takes place once, unlike with other shells.

VARIABLE SUBSTITUTION

Shell variables are used by the shell to maintain information about the users current environment and by the user for his own ends. Ssh provides three different types of variables: string and null variables which are modified with the set and unset commands, and numeric variables which are modified with the nset and unset commands.

String variables are lists of 1 or more variable length words, while null variables contain no information, and finally, numeric variables are long integers with a single value. Null variables are usually used for true/false conditions where their existence, or lack thereof, signifies their value.

After alias parsing, variable parsing is performed. Like the switches in aliases, variables are prefixed with the `$' or `$$' for environment variables, to signify that the value of the variable being named is to be substituted here. This substitution is recursive and variables embedded in words produce every possible combination. Example:

> set var = aa bb cc
> ls ~$var     # will yield:

> ls ~aa ~bb ~cc

Individual words in a string variable may be substituted by placing an expression in `[' and `]' following the name of the variable. For example:

> set var = aa bb cc
> ls ~$var[1]  # will yield:

> ls ~bb

Variable names may be enclosed in `{' and `}' to separate them from other letters so that they may be embedded in a word. Example:

        /usr/tmp/${file}ext     "$${USER}XXXX"

Prefixing a variable name with `$#' or `$$#' for environment variables, returns the number of words contained in a string variable or the number of letters in an individual word. Prefixing a variable with `$?' or `$$?' for environment variables, returns the type of variable or 0 if it is not defined. Environment variables are considered string variables always. The valid types are:

       0 Not defined

       1 String variable

       2 Numeric variable

       3 Null variable

The metacharacter `$<' reads in a line of text from the stdin and replaces itself with the input read.

LOGICAL ASSIGNMENT SUBSTITUTION

The shell maintains a list of assignments that can be used to reference file and directory prefixes with a minimal amount of typing. Assignments are defined and undefined using the commands assign and unassign. Logical assignments are placed at the beginning of the word, followed by a `:', then possibly followed by more path components or filenames. Logical assignment substitutions take place before wildcard substitution, so wildcards may be placed in the assignment to make conditional assignments. Examples:

> assign inc "{{/usr/include,/usr/include/sys}}/"
> more inc:ioctl.h             # Will yield:


  more {{/usr/include,/usr/include/sys}}/ioctl.h

  # To finally yield after wildcard substitution:

  more /usr/include/sys/ioctl.h

Obviously files and directory paths are not the only possible use for logical assignments. Assignment processing can be circumvented by setting the shell variable noassigns.

WILDCARD SUBSTITUTION

Any word containing the characters `*', `?', `[', `{' or begins with `~' is considered a candidate for wildcard expansion, provided that the shell variable noglob does not exist. The word is then parsed and the file system is examined to find files that match the pattern. If matches are found then the wildcard pattern is replaced on the command line with a sorted list of filenames that matched the pattern. If the pattern matcher fails to find a valid match then it prints an error and the command is aborted, unless the shell variable nonomatch is set, in which case it is not an error and the original pattern is left on the command line.

Hidden files (those beginning with a period `.') are also included in wildcard searches unless the nodots shell variable is set, in which case they are ignored unless explicitly specified. The file system constructs `.' (current directory) and `..' (previous directory) are always ignored for purposes of wildcard searches.

The various wildcard characters have the following meanings:

~

Followed by a user name expands to the full path of that users home directory. `~' alone expands to the shell users home directory as defined in the shell variable home. `~' followed by a wildcard expression searches the passwd file for possible user names and replaces them with the full path to their home directory.

*

Matches zero or more characters.

?

Matches any single character.

[...]

Matches to any single character that is present inside of the []'s. A `-' in between characters denotes a range of characters, where any single character in the range is matched.

[^...]

Matches to any single character that is not present inside of the []'s. Just as `[...]' above.

{...}

Comma `,', separated words are automatically expanded (macro expansion). Words inside of {}'s may be directories or more wildcard expressions. Braces inside of the outermost level of braces becomes wildcard expansion and only matches files that exist.

{^...}

Like `{...}', but matches anything not contained in the comma separated list. Braces inside the outermost level of braces becomes wildcard expansion like above and only match files that are not specified in the expression.

REDIRECTION

The standard input, standard output and standard error of a command may be redirected with the following syntax:

< name

Open the file name as the commands standard input.

<% descriptor

Opens the file or pipe referenced by descriptor as the commands standard input. If the descriptor does not exists, a pipe is automatically made. The read portion of a pipe is closed at the shell level.

<<% descriptor

Opens the file or pipe referenced by descriptor as above, but the read portion of a pipe is left open at the shell level.

> name

>! name

>& name

The commands stdout `>', stderr `>!' or both `>&' will be redirected to the named file, overwriting any data and creating the file if necessary. If the shell variable noclobber exists then the file must not exist or an error results in order to prevent the accidental destruction of files.

>% descriptor

>!% descriptor

>&% descriptor

Opens a file or pipe referenced by descriptor for output on the commands stdout, stderr or both. Like `<%' above, a pipe is created if the descriptor does not reference a pre-existing object. The write-side of a pipe is also closed at the shell level as per `<%'.

>> name

>>! name

>>& name

Like `>', `>!' and `>&' above, except that the redirection appends to files rather than overwriting them. If the variable noclobber exists then it is an error for the file not to exist.

>>% descriptor

>>!% descriptor

>>&% descriptor

As `>%', `>!%' and `>&%' above, however the write-side of the pipe remains open at the shell level for further use.

cmd | cmd2

cmd |! cmd2

cmd |& cmd2

Pipes the output of the stdout `|', stderr `|!' or both `|&' of cmd into the stdin of cmd2.

The redirection constructs `<%', `>%', etc, can be used to implement tree-like pipe structures and `reverse piping'. Examples:

    errparse <% err > errors & cmd >!% err | cmd2


    cmd1 <% xx | cmd2 >% xx

In the first example, the stdout of `cmd' is piped to the stdin of `cmd2' at the same time that the stderr of `cmd' is piped to the stdin of `errparse', which is spawed in the background, so all three commands run concurrently. In the second example the two commands are made to communicate with each other via their stdin and stdout.

EXPRESSIONS

The shell supports C like expressions that are used in some builtin commands and for indexes for string variables. The following operators are supported:

( )
! ~ ++ -- + - (unary)
* / %
+ - << >> & ^ |
< <= > >= == != !~ =~
&& ||

Numbers may be expressed either as decimal, hex (with a leading 0x or 0X), octal (with a leading 0), or binary (with a leading 0b or 0B). For example: 255, 0x00FF, 0377 and 0b11111111 are all equivalent. In ssh, all numbers are signed longword integers. `++' and `--' only operate on numeric variables. Strings and string variables can only be compared together and only then, can two strings be compared. A single string equates to true. The operators `=~' and `!~' compare a string (on the left side of the operator) and a pattern (on the right side of the operator) for a match or lack thereof.

A dash `-' followed by one of `defgmoprsuwxz' test the next argument, taken to be a filename, for some property of that file. These switches have the following properties:

-d

True if file is a directory.

-e

True if file exists.

-f

True if file is a regular file.

-g

Returns the Group ID of the file.

-m

Returns the entire mode word of the file.

-o

True if file is owned by the user.

-p

Returns the protection bits of the file.

-r

True if file is readable.

-s

Returns the size of the file in bytes.

-u

Returns the User ID of the file owner.

-w

True if file permits writing.

-x

True if file is executable.

-z

True if file is zero length.

BUILTIN COMMANDS

Builtin commands are normally executed within the context of the shell, however, if they are included in a pipeline (except as the last command in the pipeline) or placed in the background, they are then executed in a subshell. Multi-line commands like for-next, repeat-until, and if-then-else-endif commands are only usable in shell scripts.

alias [<name> [<wordlist>]]

Alias with no arguments lists all the aliases, One argument, which may be a wildcard, lists all aliases that matches it. Two or more arguments makes an alias assignment.

assign [<name> [<assignment>]]

Assign with no arguments lists all logical assignments, One argument returns the value of that particular assignment. Two arguments makes or changes a logical assignment.

bg [<job number>]

With no argument, bg puts the first stopped job it finds into the background and starts it running. A particular job can be selected by providing bg with an argument specifying the job number.

break

This command is used to break out of one of the looping commands or a switch statement and continue execution at the end of the loop or switch.

cd [<path>]

Cd without an argument changes the current working directory to the users home directory, as defined by the shell variable home. Cd attempts to change dir into the argument given, failing that, it will search for the directory in the directories defined in the shell variable cdpath.

continue

Continue skips over any remaining commands inside of a loop and continues execution of the next loop, if applicable.

dec <var> [<var> [<var> ... [<var>] ... ]]

decrement numeric variable by one.

else <wordlist>

The single line , when placed immediately following a single line if-then command in a script file will execute the wordlist as a command, provided that the if condition was false. This command must follow immediately the if statement and can only be used in script files.

eval <wordlist>

Eval executes the wordlist as a command in the context of the current shell. Usefull for executing the resulting wordlist of a command string or variable.

exec <wordlist>

The specified wordlist is executed as a command in place of the current shell. Due to the nature of this command, only the rightmost command in a pipeline will be executed, as the shell will cease to exist when it is successfully executed.

exit [<expression>]

The shell exits either with the value of 0 (without an argument) or with the value of the resulting expression.

fg [<job number>]

Brings the first job found or the specified job into the foreground, restarting them if they were stopped.

for <var> = <expr> to <expr> [step <expr>]

  ...

next

The variable <var> is set equal to the first expression, and is incremented by the step value (default is 1), executing all the commands in between the for and next statements until it reaches or exceeds the resulting value of the second expression.

foreach <var> <wordlist>

  ...

endfor

The variable <var> is set to each word in <wordlist> successively in turn, executing all the commands between the foreach and endfor statements for each word in <wordlist>.

goto [-f] [-r] [-t] <label>

Goto searches the script file for a matching label, defined by the label command and continues execution from there. Goto uses several options to improve its efficiency in this search. The following switches have these meanings:

-f

Search forward from the current position.

-r

Search backward from the current position.

-t

Start search at the top of file.

history [-r] [-n] [-nn]

Displays a list of the saved command history. It supports the following switches:

-r

Display history list in reverse order.

-n

Do not number output of history list.

-nn

Display only nn histories.

if <expression> then <command>

If the expression evaluates to true (non-zero), then the statement is executed. To implement pipelines and complex commands and redirection, the command should be enclosed in ()'s to insure that parsing is not done on command until it is to be executed. This command may be immediately followed by a single line else if executed in the context of a script.

if <expression> then

  ...

else

  ...

endif

Like the single line if, the multi-line if, executes all the commands in between the if-then and else or endif statements if the expression evaluates to true. If the expression evaluates to false and an else statement exists, then the commands in between the else and endif statements are executed.

inc <var> [<var> [<var> ... [<var>] ... ]]

Increment the given numeric variable(s) by one.

input [-c] [-e] [-w] [-n] [-p] <var>

Inputs a line or character from the stdin. The way input reads in the data is modified by these switches:

-c

Reads a single character from the stdin and then places the character in the variable immediately, without echoing the character to the screen.

-e

Like `-c', except the character read is echoed to the screen.

-w

Splits the input line into words separated by spaces and tabs.

-n

Does not overwrite or create the variable if nothing was typed in (ignored for `-c' and `-e').

-p

The next word is taken to be the prompt string, which will be printed before input is taken.

intr [+] [-] <signal list>

Intr is used in script files to set which termination signals that the shell will abort scripting on. By default the SIGPIPE signal is ignored. Intr with no arguments lists all the termination signals that the shell acts on. The `-' option removes all signals from the list, and the `+' option adds all signals to the list. <Signal list> is a list of valid signal names that toggle the signal on or off. Valid signal names are:

HUP INT QUIT ILL TRAP IOT EMT FPE KILL BUS SEGV SYS PIPE ALRM TERM URG STOP TSTP CONT CHLD TTIN TTOU IO XCPU XFSZ VTALRM PROF WINCH USR1 USR2

jobs

Prints the number, process ID, status and job name of the all jobs that the shell is tracking.

key [-r] [-c] [-fn] [-gn] [-ln] [<keylist> [<wordlist>]]

Key allows the user to setup and maintain multi-level key macros and assign editing functions to specific key sequences. It supports these switches:

-r

Executes the key macro as a command immediately.

-c

Clears the line before inserting the key macro.

-fn

Assign key sequence to edit function n. Valid edit functions are:

 0   No function.

 1   Previous history.

 2   Next history.

 3   Move left.

 4   Move right.

 5   Delete previous character.

 6   Toggle insert/overstrike.

 7   Move to start of line.

 8   Delete to the right.

 9   Move to the end of line.
10 Kill to end of line.
11 Restore line.
12 Kill line.
13 Quoted insert.
14 Find matching history.
15 Kill to start of line.
16 Filename completion.
17 Forward word.
18 Backward word.
19 Parse line and replace.
20 Kill word.
21 Make next character a control character.

-gn

Defines a gold key that makes the current keypad level equal to n when the key sequence is entered. There are a maximum of 10 keypad levels (0-9).

-ln

Keypad level that this macro is being defined for. Keypad level 0 is the default.

label <lablename>

Defines a label for use with the goto command.

limit [<resource> [<resource limit>]]

Without arguments, limit displays the current resource limits for cpu, filesize, datasize, stacksize, coredumpsize and memoryuse, specified in K (1024) bytes or seconds for cpu usage, or unlimited for unlimited resources in that area. With one argument, limit displays the current limit for that resource. With two arguments, limit sets the limit for that resource.

login

Starts a new session by replacing the shell with the system login command.

logout [<wordlist>]

If the shell is a login shell, then logout saves the history to the .hist file in the users home directory, then sources the users .logout file located in their home directory, passing the wordlist in the shell variable argv to the script and then exits. If the shell is not a login shell, the shell simply exits.

protect <var>

Makes the variable ``protected'', in that it cannot be reset or unset.

repeat

  ...

until <expression>

Executes commands inside of the repeat and until commands until the <expression> evaluates to true.

sclose <descriptor> [<descriptor> ... <descriptor>]

Closes open files or pipes referenced by <descriptor>.

secho [-n] [-w] [-e] [-] [<wordlist>]

Secho is the shells version of the echo command, with the wordlist being routed through the shells stat facility to convert certain `%' switches (see STATUS SWITCHES below), unless the `-e' switch is given. These switches to secho are supported:

-n

Do not print a newline at the end of the wordlist.

-w

Toggles printing of a newline after each word.

-e

Toggles interpretation of status switches off and on.

-x

Everything after this switch is taken to be an expression to be evaluated and the result printed.

-

All dash arguments after this are taken to be words to be printed. No further arguments are parsed.

set [<var> [< = | += > <wordlist>]]

nset [<var> [<operator> [<expression>]]]

Set

or nset list the value of all known variables when used with no arguments. With only one argument they creates a null variable of name <var>. Set when used with a `=', sets the variable equal to the wordlist. When used with `+=' set appends the wordlist to the wordlist in <var> (useful for quickly adding directories to the path variable). Nset is used to create and modify numeric variables and supports the following numeric assignment operators: `=', `+=', `-=', `*=', `/=', `|=', `^=', `<<=' and `>>='. The operators `++' and `--' can be used to increment or decrement the variable by one.

setenv <name> [[=] <wordlist>]

Setenv displays and sets environment variables for the shell. With one argument, setenv displays the value of the environment variable <name>. With two or more arguments, setenv assigns the <wordlist> to the variable <name>. The equal sign `=' is optional for setenv.

shift <shiftval> <var> [<var> ... [<var>]]

Shift shifts words left in <var>, <shiftval> number of times. This is useful for removing the beginning words in the shell variable argv so that it may be fed to a foreach command to parse the arguments fed to the script.

sopen [<descriptor> [<file> <modelist>]]

With no arguments, sopen lists all open files and pipes and their modes. Provided the descriptor, sopen lists the file or pipe it references and modes for that descriptor. Sopen with three or more arguments opens a file or pipe and associated with a logical descriptor name <descriptor> which is used in the sread, swrite, sseek and sclose calls and the `<%' `<<%' ,`>%', etc redirections to reference the open file or pipe. Mode is one of the following, defining how the file is to be opened:
       READ Open for reading

       WRITE Open for writing

       APPEND Append to end of file.

       TRUNCATE Truncate file upon open.

       PIPE Open a pipe for reading and writing

A file may be open for reading and writing at the same time. When a PIPE descriptor is made, the pipe is made to be read and writeable until the first sread or swrite is performed on the pipe, at which time the mode of the pipe is selected (this is done to allow the user to launch any pipe redirections before reading/writing on the pipe).

source [<file> [<file> ... [<file>] ... ]]

Source with no file arguments, reads input from the user, up until it reaches the `exit' command and then sources the input. With file arguments, source sources each file in turn. Files sourced in this way are executed in the context of the shell, so changes made to the shell environment are permanent.

sread <descriptor> [-c] [-l] [-w] [-bn] <varlist>

Sread reads input from a file or pipe referenced by the logical file descriptor <descriptor> into a variable. Switches may be interspersed on the command line to change how the data is read for each variable. Valid switches are:

-c

Read a single character.

-l

Read in a line and do no processing on it.

-w

Read in a line and break it into words separated at spaces and tabs. Useful for separating input into fields which can be easily manipulated.

-bn

Read in n bytes.

A read past end of file returns an error and sets the shell variable EOF with the name of the offending descriptor.

sseek <descriptor> <mode> <expression>

Sseek sets the file pointer for the file referenced by <descriptor> based upon the mode. Valid modes are:
       INCR Increment the file pointer.

       SET Set the file pointer.

       XTND Extend the file pointer past the
EOF.
<Expression> is the resulting value used to change the file pointer with. Upon a successful seek, the shell variable filepos is updated to reflect the current file pointer value. Sseek's cannot be performed on descriptors referencing a pipe.

stop [<job number>]

Stops the first running background process found in the job queue, or stops the specified job by sending the jobs the SIGTSTP signal.

switch <string>

  case <pattern list>

    ...

    break

  ...

  default

    ...

    break

endsw

Switch

compares string against each case label, that is variable expanded and may be a filename wildcard expression, until it finds a match. If it finds a match, then it begins executing lines after the case until it reaches a break statement or endsw, falling through other case statements. If no match is found and there exists the default label, then commands are executed after the default label. If no match was found and no default label exists, then the switch is aborted and execution continues after the endsw command.

swrite <descriptor> [-n] <wordlist>

Swrite writes the specified wordlist to the file or pipe referenced by <descriptor>, which may contain the shells status switches (see STATUS SWITCHES below).

term [<capability ID> [<character sequence>]]

Term prints the current terminal that the shell is using and several of the escape sequences that the terminal understands that the shell will use. The values of these sequences may be shown by specifying one of the valid terminal capabilities. A terminal capability may be altered by specifying an additional character sequence after the capability ID. The following capabilities are used by the shell:
       SO Begin standout mode.

       SE End standout mode.

       CE Clear to end of line.

       KS Function keypad enable.

       KE Function keypad disable.

       DC Delete character.

       IC Insert character.

       DS Display status line.

       TC Begin writing on status line.

       FS End writing on status line.

       HS Has status line (1=TRUE).

The shell is intelligent enough to work without almost all of the above terminal capabilities, but CE is recommended. DC and IC may greatly improve speed of editing for slower baud rates as well. Unsetting DC and IC for slow-editing terminals at higher baud rates may also improve editing speed.

umask [<expression>]

Umask with no arguments returns the current file protection mask in octal, otherwise umask sets the value of the file protection mask to the value of the resulting expression.

unalias <patternlist>

Removes all aliases that match the given wildcard patterns.

unassign <assignmentlist>

Removes the given assignments from the list of known assignments.

unkey [-ln] <key sequence>

Removes the key macro associated with the given key sequence. The switch -ln specifies the keypad level the macro is to be removed from.

unlimit <resource>

This command attempts to remove the system imposed limits on the specified resource, if possible. Valid resources are the same as those given with the limit command: cpu, filesize, datasize, stacksize, coredumpsize and memoryuse.

unset <variable>

Removes the named variable from the list of known variables.

unsetenv <variable>

Removes the named variable from the environment.

usage

Displays some information about the system resource usage of the shell, including: Total user and system time used by the shell, the resident set size (RSS) of the shell, total page reclaims and faults, number of times the shell has been swapped, number of I/O pages read and written and the number of signals received. The amount of valid information maintained and the true meaning of the above information may vary from OS to OS.

version

Displays the shells version information.

while <expression>

  ...

wend

Executes commands inside of the while - wend loop so long as the expression evaluates to true.

SHELL VARIABLES

Certain variables have special meaning to the shell. The variables cwd, failat, history, home, host, insert, path, pid, prompt, status, term, tty, and user are always set upon login. The variables echo, remotehost and verbose might also be set at login. Aside from the variables cwd and status which are updated by the shell automatically, these variables are only set once at login.

For the variables user, term and path, the shell attempts to use the environment if possible to set these values initially. Variables like term and path, are likewise automatically exported to the environment any time they are changed by the user.

The following variables have special meaning to the shell:

argc

Defined to be equal to the number of words in argv, therefore it is essentially the same as `$#argv'. Only defined when argv is defined.

argv

Set to the arguments passed to an auto-executed shell script, including the command itself in `$argv[0]'.

cdpath

Directories specified in this string variable are searched in the event of a failed `cd' to find a valid subdirectory.

cwd

This variable is maintained by the shell to be reflect the current working directory at all times. This variable is automatically exported to the environment.

echo

Set when the -x or -X command line option is given. Causes the shell to echo the entire command line before each command is executed. Useful for debugging shell scripts.

EOF

This string variable is set by the command sread when it reads the end of file. The resulting string is equal to the name of the file descriptor.

failat

The value of this numeric variable is used in script files when a command returns an error condition (greater than 0). The value of failat is checked against the return status of the command, and if it is lower or equal to the status, then the script file is aborted.

filepos

This numeric variable contains the current file pointer position as returned by the last successful sseek command.

history

This numeric variable determines the number of histories maintained by the shell. By default this variable is set to 30 histories by the shell, and is also set automatically by the shell when it reads the first line in the .hist file in the users home directory, which should contain the number of histories to save. The history list will never be less than one entry, even if the variable is unset.

home

Set to the home directory of the user. Used by cd to return to the users home directory, when no arguments are given it, and by the wildcard character `~'. This variable is exported to the environment automatically.

homedirs

This string variable contains a list of user directories for use with the `%~' status switch.

insert

Used by the input functions to determine if the user is in insert mode or overstrike mode. Insert mode is selected if the variable exists.

mail

This string variable contains a list of files that are checked after each command completion and if the interval specified by the variable mailchkint has elapsed, to see if they contain new mail. If new mail is found, then the shell reports to the user `You have new mail.' If the mail file is not the first entry in the mail variable, then the filename with the new mail is also reported. This message may be modified by setting the mailnotice variable. This variable is exported to the environment automatically.

mailchkint

This numeric variable defines the minimum interval that new mail is to be checked for.

mailnotice

The first word of this string variable defines the message the shell prints in the event of new mail. The second word, if present defines what to print for the status switch `%n'.

noassigns

If this variable exists, then logical assignment processing is not performed by the shell.

nobgnull

If this variable exists, the shell will not redirect to /dev/null by default for jobs spawned in the background.

noclobber

If this variable exists, then it is an error for the user to attempt to redirect into a file that already exists, or perform appended redirection into a file that does not already exist.

nodots

When this variable exists, files preceded by a dot `.', therefore hidden files, will not be considered candidates for pattern matching, unless the dot is explicitly given in the expression.

noglob

If this variable exists, then wildcard expansion is not performed by the shell.

nohup

If this variable exists, then jobs executed in the background are made to ignore the SIGHUP signal.

nonomatch

When this variable exists, then it is not an error for a wildcard expression to not match any files and is not removed from the command line.

notypeahead

When this variable exists, then the shell throws away any pending input (typeahead), before it prints the prompt and begins accepting input for the command line.

path

This string variable contains a list of directories in which the shell searches for commands to be executed by the user. If no path variable exists, then the path is considered to be the current directory only. This variable is exported to the environment automatically.

prompt

This string variable is printed before each command is read. This variable may contain status switches as well. Only the first 80 characters of this variable (after status switches are interpreted) are used.

remotehost

Set to the remote login host as specified in the /etc/utmp file for your login session if you are logged in remotely.

statline

This string is printed in the status line after every command completion if it is possible to do so, i.e. the terminal must support a status line. Like the prompt variable, the statline may contain any of the status switches.

status

This numeric variable is maintained by the shell, and may not be altered or unset by the user. This variable contains the exit status of the last command to complete (including completed background jobs). The lower 8 order bits are formed by the exit status of the command, the next 8 order bits are formed from the value of the killing signal (if any). To determine if the command exited abnormally you would use an if statement similar to:

     if ($status>>8) then ...

To separate the status information:

     nset exitval = $status

     nset signal = ($exitval>>8)

     nset exitval &= 255

Shell builtins return a `1' upon failure, otherwise they return a `0'.

term

This string variable is used to set the terminal type of the current login session. The terminal capabilities used by the shell (as displayed by the term command) are automatically loaded whenever this variable is changed. This variable is automatically exported to the environment whenever it is altered.

timeout

When this numeric variable is set, the shell will logout automatically after the number of seconds defined by the variable has elapsed and no input has been entered by the user. This count-down only happens when the user is at the shell prompt and idle.

verbose

Set by the -v and -V command line options. When this variable exists, the command line is printed before any parsing is done on the command line.

NON-BUILTIN COMMAND EXECUTION

When a command to be executed is determined to not be a builtin command, the shell searches the path list defined in the path shell variable for the requested command. If the command is found then the shell checks to see if the command is actually a directory, if so then it attempts to make it the current working directory. Otherwise the shell forks and attempts to execute the command.

If the command was spawed to be a background process with the `&!' metacharacter, then the shell closes stdin, stdout, and stderr (input and output redirections will not be affected by this), forks several more times and attempts to dissociate the terminal. Due to the extra forking involved in the terminal dissociation process, the shell will lose track of the child process.

Immediately after forking, the shell determines if the job was a process leader. Process leaders are the right most commands in pipelines. Processes not in pipelines are also process leaders. If a job has been determined to be a process leader and the job was not spawned as a background job, then the shell relinquishes control of the terminal, adds an entry in the shell job table and waits for the job to complete. The process is nearly identical for non-process leaders, however non-process leaders inherit the same control terminal as the process leader.

Should the process leader complete before any of the non-leaders, then the remaining processes are certain losers as the shell will regain control of the terminal when the process leader completes. Since most non-leaders in pipes would be killed by the broken pipe or by other means, this is not really a problem.

If the shell fails in its effort to exec the command, and it is determined that it failed because the file that it was attempting to execute was not a binary file or a script file which specified its shell in the first line, then it will attempt to auto-source the file. Files auto-sourced in this manner, have the arguments passed to them in the shell variables argv and argc. Files sourced in this manner are executed in a subshell and will not affect the environment of the parent shell.

Files that are sourced or auto-sourced, are read entirely into a buffer and parsed before they are executed. Command strings are also parsed and executed at this time. The resulting buffer is then sourced, performing the neccessary variable, logical assignment and wildcard expansion at each line.

STATUS SWITCHES

The following switches may be embedded in the words of the prompt and statline variables and passed to the secho command for printing. Their meanings are:

%t

Replaced by the time in hh:mm [am|pm] format.

%M

Replaced by the time in hh:mm military format.

%w

Replaced by the name of the day of the week.

%d

Replaced by the day of the month.

%m

Replaced by the name of the month.

%y

Replaced by the year.

%T

Replaced by the time the user has been logged in, in hh:mm format.

%j

Replaced by the number of jobs the shell has active.

%p

Replaced by the path of the current working directory.

%P

Replaced by the last path component in the current working directory.

%~

Replaced with the path, substituting a `~' for a users home directory path.

%u

Replaced with the number of users currently logged into the system.

%U

Replaced with a list of the users logged in.

%l

Replaced by the number of times the user is logged in.

%n

Replaced with an `*' or the second word in the mailnotice variable when you have new mail, or nothing at all when you do not have new mail.

%i

Begins standout mode.

%I

Ends standout mode.

%<TC>

Where <TC> is one of the known terminal capabilities, therefore: SO, SE, CE, KS, KE, DC, IC, DS, TC, FS and HS.

%%

Replaced with a single percent `%'.

SSH ARGUMENTS

If argument zero is a dash `-', then the shell is taken to be a login shell. Ssh interprets the following arguments:

-c

The next word is executed as a command.

-e

The shell exits if any command terminates abnormally or returns a non-zero exit status.

-f

The shell skips sourcing of the the .sshrc file in the users home directory, making it start faster.

-n

Commands are parsed, but not executed.

-t

A single line is read and executed.

-x

Causes the echo variable to be set, echoing commands before execution and after all parsing is done.

-X

As with -x, except that echoing begins even before the system .sshrc file is sourced.

-v

Sets the verbose variable, which echoes commands before any parsing is done to the commands.

-V

Is to -v what -X is to -x.

AUTHORS

Steve Baker (ice@judy.indstate.edu)

  and
Thomas Moore (dark@judy.indstate.edu)

  - Wildcard routines (wc.c)

FILES

/etc/.sshrc Read first at startup.
~/.login Read by login shells after `/etc/.sshrc'.
~/.sshrc Read at startup after `~/.login'.
~/.logout Read by login shells at logout.
~/.hist History save file.
~/.second Secondary password store.
~/.warning Failed second-password login notification.
/etc/passwd Source of home dirs for `~'.
/etc/utmp Source for finding current logins.
/etc/termcap Source for terminal capabilities.
/dev/null Auto-redirect file for background jobs.

BUGS AND LIMITATIONS

1.

Words can be no more than 1024 characters. System limit of 10240 byte commands, except for shell builtins.

2.

Should maintain a "current job" pointer or maintain a restart priority within the process table.

3.

Behavior for deciding what gets alias substituted is screwy. Since alias substitution is only performed once, the following shouldn't work:

    > alias more less

    > alias x (cat yyy | more)

    > x  # will yield:

    > cat yyy | less
The ``| more'' was parsed as an alias before it was put into the alias `x', so it became `less' instead of the `more' it should have been. The parens failed to stop the alias parsing like they should do. Not too sure if this {-eally should be fixed!

4.

Should allow a secondary index for string variables to examine individual characters of a word. And should be able to use indexes when assigning values to string variables.

5.

In expressions, operators do not necessarily have the same precedence as they do in C. Parens should be used when in doubt about precedence.

6.

Limit should be a little more intelligent with reguards to setting the limits, by allowing size parameters like csh's limit.

7.

The shell really needs to understand more terminal capabilities to improve efficiency. The shell also makes pessimistic assumptions like backspace is always ascii 8, and carriage return doesn't cause a newline.

8.

A special string malloc'er should be made for the shells amazing about of small mallocs.

9.

Ssh's command line editor doesn't understand that most terminals have a maximum line width shorter than the 256 input buffer, and so it should be a little smarter and try and pull the cursor back up to the end of the previous line when you backspace at the beginning of the line.

10.

When a job is stopped in a shell script, the script should stop as well and when restarted, the script should attempt to restart the stopped job and continue normally.

11.

And many many more little things.

SEE ALSO

Index

NAME

SYNOPSIS

DESCRIPTION

LEXICAL STRUCTURE

COMMANDS

JOBS

COMMAND LINE INPUT

STATUS REPORTING

SUBSTITUTIONS

COMMAND SUBSTITUTION

ALIAS SUBSTITUTION

VARIABLE SUBSTITUTION

LOGICAL ASSIGNMENT SUBSTITUTION

WILDCARD SUBSTITUTION

REDIRECTION

EXPRESSIONS

BUILTIN COMMANDS

SHELL VARIABLES

NON-BUILTIN COMMAND EXECUTION

STATUS SWITCHES

SSH ARGUMENTS

AUTHORS

FILES

BUGS AND LIMITATIONS

SEE ALSO