Go to the first, previous, next, last section, table of contents.

Builtin Commands

A number of commands are executed directly by the shell, rather than by forking and executing some other program. These commands are known as builtins. Some commands are provided as builtins because they affect or report on the state of the shell, and so the function they provide could not possibly be provided by an external program. Other commands are provided as builtins for improved efficiency and to insure that the particular command is available, independent of what system the shell is being run on.

Some builtins in this second category has slightly different syntax or semantics to standard versions of the same command, and forcing them upon the user could lead to confusion. Such commands have been marked as hidden and can only be accessed indirectly through the builtin command (see below). These commands are marked with a '';

When used in command substitution (See Substitutions) it is often not necessary to fork before executing the command if the command is a builtin. Those builtins which do not cause a fork when used in command substitution are marked with a '*';

`. [-hn] file'

Shell commands are read from the given file. If the `-n' flag is not present, the commands are executed as they are read. If the `-h' flag is present, commands are added to the history. A file name of "-" causes commands to be read from standard input. "' FIXME command on how . -- - will read from the file '-' Otherwise a path search of PATH is made, controlled by the third character of WHICH looking for the file (See Path Searching).

`:'

This command is equivalent to true. It does nothing and returns a successful status.

`[ test-options ]'

`test test-options'

Perform the tests described and return appropriate status. See test(1) for further details.

`alias'

`alias name'

`alias name value'

This command allows defining and viewing of aliases (See Aliases and Functions). The first form lists all known alias and functions. The bodys of functions are not displayed. The second form prints the definition of the given alias. The third form set the given name to be an alias with the given value. Any previous alias or function with that name is discarded.

`apollopad -f'

`apollopad -k keyname [definition]'

`apollopad -xdmc dm command'

The apollopad command is available only on Apollo workstations. It provides some direct access to the pad system calls. The first form (-f) issues a force_prompt command to force any half-printed line into the input window. The second form sets or (with no definition) clear the definition of the given key in the pad. The keyname should be uppercase (except for lower case letters) and padded with spaces to be 4 characters long. Note that this key definition is local to the given pad. The third form executes a DM command. If there are any spaces or other special characters in the command, it must be quoted. The particular pad affected is the one on which stderr (file descriptor 2) is open.

`bg [job]'

This command is only available on systems which support full job control (BSD4). Its function is to continue to named job, or current job if no name is given, int the background. See Job Control.

`break [n]'

Break out of `n' enclosing loop bodies (while, until or for), 1 by default.

`builtin'

`builtin command [ args ]'

The first form lists all defined builtin commands, and indicates which are hidden, and which are internal. "' FIXME better name than internal The second form runs the given builtin command with any args given. This is the only way to access hidden builtins or builtins with the same name as some alias or function.

`cd [ directory ]'

`chdir [ directory ]'

Change the current working directory to that given, or the value of the HOME variable if none is given. The directory is searched for in using the CDPATH variable and the second character of WHICH (see Path Searching). If the directory is found somewhere other than the current directory, and it was the cd command that was given, then the name of the directory changed to is printed.

`continue [n]'

Continue execution at the begining of the `n'th enclosing loop ( `n' is 1 by default). This command is similar to break.

`cwd'

Print the name of the current working directory (as found from the '.' parameter, see Parameters and Variables) after replacing any prefix which is a users home directory with the name of the user preceded by a '~'. If the owner of the directory is the current user, the name is not printed, only the '~'. If any arguments are given they are printed, rather than the current directory, again with home directory names replaced. The home directory name replacement only works if the directory is beneath the home directory of the owner of the directory.

`date'

Print the current system date, or the time specified in an argument, according to a given format. See ash_date(1) for further details.

`echo'

Print arguments to standard output, normally separated by a space, and terminated by a newline. If the first argument begins with -e, -y or -n, then it is not printed, but instead affects the way in which subsequent arguments are printed. Depending on that first argument, characters preceeded by a slosh (sloshchar) are interpreted specially. These characters and their interpretation are:

'\\'

print a slosh

'b'

print a backspace

'c'

suppress the newline normally printed after all arguments are processed.

'f'

print a form feed

'n'

print a newline

'r'

print a carriage return

't'

print a tab character

'v'

print a vertical tab

'?'

print the BEL character to ring the bell

'0'

The following digits, up to 4 of them, are interpreted as an octal number, and the character with that value is printed.

A leading '-n' in the first argument suppresses slosh interpretation and the trailing newline. A leading '-y' in the first argument suppresses slosh interpretation, but leaves the trailing newline to be printed. A leading '-e' enables slosh interpretation. This is the default, but is useful in cases where the first argument to be printed may infact start with one of -e, -n, -y. If the first argument is special, and contains more than justtwo characters, the subsequent characters are printed between arguments, rather than the normal space.

`edctl -f editor-program-file'

`edctl -E[edmode] string'

`edctl -L'

`edctl -e exitstr'

`edctl -n opcodelimit'

`edctl -w width'

Edctl is used to control and interface to the line editor. See Line Editting. Given an editor-program-file, the content of that file will be read in and used as the editor program. Given an edmode (a small number) and a string, that string and number are passed to the editor program, and the resulting string is sent to standard output. If no edmode is given, 1 is assumed. The L flag set lines line mode, effectively disabling the editor for interactive work. Each input line is still passed to the editor for history substitution. exitstr is a string that can be used to abort a user-loaded editor program. Typing the characters in that string sequentially will cause the standard editor to be reinstated. This string is five escape characters initially. An opcodelimit limits the number of editor program instructions that may be executed between user keystrokes. If the number is exceeded, the standard editor program is reinstated. This helps guard against losing control to infinite loops in programs under development. The width setting control the horizontal scrolling in the editor and also the formatting of lists generated by filename completion and the ls-F builtin. "' FIXME what about -z

`eval'

The arguments are joined together with interveneing spaces and the resulting strings is treated as input to the shell and is parsed an executed. This provides for multiple processing of arguments. "' FIXME need an example here

`exec [ -p program ] command args'

The given program, or that found by searching PATH for command is executed without first forking, thus effectively terminating the shell. When the exec'ed prgram terminates, control will NOT return to the shell. If no command is given, all i/o redirection is performed and made permenant to the shell processes, thus file descriptor for the actual shell, rather than just for child processes can be closed and reopened. "' FIXME comment about different handleing of local variables.

`exit [n]'

Terminate the shell, providing return status `n' to the calling program. If `n' is not given, the value of the last simple command is returned. Exit will fail if there are and stopped jobs.

`export [-a]'

`export [-a] name[=value] ...'

The first version prints a list of all variables (or aliases if the `-a' flag is given) that are currently marks for export. The second version marks for export all the variables (or aliases) listed and copies their current value into the export list for subsequent processes. If any name is followed by an equals sign, then the value given after that is assigned to the variable or alias before it is exported.

`false'

Any arguments are ignored and the return status is set to 1 (indicating failure).

`fg [job]'

On system that provide some form of job control, fg will continue the named job (or the current job) in the foreground. Systems that do not support full job control are not capable of moving to the foreground jobs that are running in the background, only jobs that are stopped.

`history [-ntdh] [num]'

Print or change the history list. Normally, the entire history is printed, with each entry prefixed by its entry number. Giving a number causes only the last that many entries to be printed. The `-n' flag suppresses printing of entry numbers. The `-t' flag cause each history entry to be prefixed by the time that it was entered. The `-d' flag causes the referenced history entries to be removed instead of printed. The `-h' flag causes the following number to be interpreted as history entry number, and only that entry is printed or deleted.

`import [-pl] [namelist]'

Import provides access to the environment supplied to the shell when it was started. "' This is particularly useful for setuid scripts With no arguements, a list the names of all entries in the import list is printed, one per line. With the `-p' flag, the values of those names given are printed, each followed by a newline. If no names are given, all values are printed. The `-l' flag lists the entries for the given names (or all names) printing the full content of the entry (name=value), one per line. If there are no flags given, each name is looked up in the import list and, if it exists, the variable of that name is set to the value in the import list. "' FIXME what if not a valid variable name?

`jobs [-n] [jobname]'

Print information on current or recently terminated jobs. Normally, all jobs that still have active processes (whether running or suspended) or that that have terminated recently and have not had their status reported are printed. along with their sttus and process number. If the `-n' flag is given, then only jobs which have changed state in an interesting way (as defined by the NOTIFY variable) are printed. If a job name is given, on the job is printed. If no job of that name exists, a failure status is returned. The order in which jobs are printed is most recently used first. Thus the first job printed is the 'current' job.

`kill [-signal] [jobname or process id]'

`kill -l'

The first form will send the given signal (or SIGTERM) to all the processes or jobs specified. The signal may be specified with a decimal number or a signal name. The second form of the command lists all valid signal names.

`ls-F'

This is a simplified form of ls(1). Any named files are listed followed by the contents of any named directories are listed on standard output. If not file or directory is named, the current directory is used. Some files are suffixed by a special character to indicate their type these characters mean:

'/'	file is a directory
'*'	file is executable
'\\'	file is a symbolic link to a directory
''	file is a symbolic link to a non-existant file
'?'	information about the file cannot be obtained

"' FIX-ME memcheck??

`notify jobname'

Mark the named jobed so that asynchronous notification will be given for all state changes. See Job Control.

`putenv name value'

Insert the name/value pair into the environment for the shell, and the pair to the export list. This is useful to affect library calls that inspect the environment such as ctime (3) and all path name lookup on Apollo workstations.

`pwd'

Print out the name of the current working directory. This may be defferent to the value of $. as the later may contain symbolic links, while the value returned by pwd will not.

`read variable-list'

`read -l variable'

One line of standard input is read and the resultin string is assigned to one or more variables. In the second form (read line) the whole line is assigned the the one variable. In the first form, leading IFS characters are stripped and the remainder is broken up, based on IFS characters into as many words as there are variables. These words are then assigned sequentially to those variables.

`readonly [-a] name[=value] ...'

The named variables (or aliases if the `-a' flag is given) are marked as readonly. If not names are given, a list of all variables (or aliases) marked as readonly is printed. If a name if followed by an equals sign and a value, the value is assigned to the name before it is made readonly.

`return [value]'

Terminates the enclosing function or alias given a return value in a manner similar to exit.

`set'

If the first argument starts with + or - the flags named in that argument are cleared or set respectively. Any remaining arguments are assigned to the positional parameters. "' FIXME does this need to be rewritten

`shift n [arrayname]'

`shift +n [arrayname]'

`shift -n [arrayname]'

Some of the entries in the named array variable (or ARGV if no name is given) are moved around. The first form discards the first n entries and moves subsequent entries down to fill up the space. The second form discards the nth entry moving subsequent entries down one space. The last form move all entries from n onward up one place, and puts a null value at the nth place. If no number is given, 1 is assumed.

`socket ....'

FIXME

`source [-hn] file'

The same as `. file'

`stat [-LRNQdimnugrsatc] flilenames/numbers'

Stat prints out information about one or more files. Some of the flags affect general behavious, other specify which item of information to print. The flags mean:

`L'

If the name refers to a symbolic link, print info about the link rather than about the referenced file

`N'

Treat arguments as file descriptors, rather than file names.

`Q'

Be quiet about errors when stating files.

`R'

If name refers to a symbolic link, print the name of the file referenced.

`d'

print the number of the device on which the file resides

`i'

print the inode number of the file

`m'

print the octal mode of the file

`n'

print the number of links that the file has

`u'

print the uid of the owner of the file

`g'

print the gid of the group owner of the file

`r'

if the file is a device special file, print the number of the device

`s'

print the size (in bytes) of the file

`a'

print the time of last access of the file (in seconds since epoch)

`t'

print the time of last modify of the file

`c'

print the time that the inode was last modified.

Multiple values are separated by spaces, and multiple files are separated by newlines.

`stop [job names/process ids]'

On systems supporting full job control, the named jobs(s) are stopped.

`suspend'

The shell is suspended (if possible) the be resumed later by being forgrounded by the parent process.

`times'

Print out the accumulated system, user and connect times for the shell.

`trap'

`trap signals'

`trap [-f] command signals'

Control signal processing. Each signal may have a string associated with it which is interpreted as commands to the shell to be executed when the shell receives that signal. Signals can be given as decimal numbers or signal names in the same way as for kill. The first form lists all currently trapped signals and the command that they will run. The second form removes any special processing for the given signals. The third form specifies the command to be run when the given signals are received. The a particular signal was ignore when the shell started, this command will have no effect unless the `-f' flag is given.

`true'

Do nothing successfully. Similar to the : command.

`ulimit [-HS] [-acdfstmvnu] [value|unlimited]'

Inspect or set various resource limits. More detailed information about the resource limits can be found in getrlimit(3). Normally the soft or current limit is inpected or set. This can be overridden with -H which causes the hard or maximum limit to be inspected or set. Thus -S is the default behaviour and need not be given. If no value is given, the resources corresponding to the given flag letters are listed. If more than one resource is listed, each is prefixed by its name, otherwise only the value is given. If a value is given, then at most one resource flag may be given, and the resource specified by that flag is set. The value may be the word unlimited, or a number optionally followed by a single letter suffix taken from `m' for megabytes, `k' for kilobytes, `b' for bytes, `s' for seconds, `m' for minutes, `h' for hours or `d' for days. The various resourse flags are:

`a'

All known resources are listed. This may not be given with a value.

`c'

The maximum size of a `core' file that can be created.

`d'

The size to which the data area of a process may grow.

`f'

The maximum size of file that may be written.

`s'

The size to which the stack may grow.

`t'

The amount of CPU time which may be consumed by an individual process.

`m'

The maximum physical memory that can be used before the process becomes a priority candidate for being swapped out.

`v'

The maximum virtual memory that can be allocated to a process.

`n'

The number of concurrent open files.

`u'

The number of concurrent processes that a user can have.

If no resource flag is given, @samp(-f) is assumed.

`umask [octal-umask-value]'

Set, or (with no argument) print the value of the shell's file creation mask. The value must be in octal.

`unalias aliases'

Remove any alias or function with the given names.

`unexport [-a] names'

The variables or aliases with the given names have their export status cleared. Subsequent changes the the values will not be reflected in the export list.

`unset variable-names'

The named variables are cleared and mark as undefined. If any of these variables are marked for export, then the corresponding entry is removed from the export list.

`vartype variable-names'

`vartype {-a[sep] } [ -i | -s ] variables'

`vartype -c var1 var2'

The first form prints out the type of the given variables. The second form sets the type of the named variables. Integer variables are specified with `-i'. String variables with `-s'. And array variables with `-a'. An optional separator character may be given with the array definition, and it should be followed by a flag indicating the type of the components of the array. The third form forces var2 to have the same type as var1.

`ver [bsd4.3|sys5.3]'

This command is only available on apollo workstations, where it is equivalent to

putenv SYSTYPE [bsd4.3|sys5.3]

`wait processid-or-jobid'

wait waits for the named process or job to terminate. If a processid is given, it must be a child of the shell. If not processid or jobid is given, wait waits for all children of the shell to terminate before completing. The exit status is undefined, as is its behaviour with stopped jobs. I should fix this.

`whence command-name'

For each command name listed as an argument, whence determines how it would try to run that command in the current state. This involves checking the name against aliases and shell functions, against builtins, and finaly by looking through the PATH for an appropriate command. It produced one line for each command name which is the command name, a colon, and then an indication of how it would run the command. While it prints the body of an alias if that is what would be run, it does not print out the code of a function, but rather just says "<shell function". This may be changed in a later release.

`which command-name'

For each command name listed as an argument, which searches the PATH to find out which actual program would be run if this command was given, and prints out the name of the program file. Exit status is 0 if any of the names actually had commands associated with them, otherwise it is 1. This is probably a bit backwards.

Go to the first, previous, next, last section, table of contents.