Builtin Command Reference Builtin vs External Commands The term "built-ins" is used to describe commands that exist within the shell itself. These utilities run faster than external commands because the code is already loaded into memory. Files of type "EXE", on the other hand, must be loaded into memory by gsh and executed. If an EXE command is executed again, it might, again, have to be loaded into memory. This results in longer execution time for the program. gsh has a number of built-in commands which allow you to work with the shell, the GNO kernel, and the shell environment. The following section describes the commands that are built-in to gsh. The "[..]" character sequence represents an optional argument to a command. The term "SIGNAL" is used to represent one of the signal names or numbers listed in Appendix D Signals. The sequence "..." means the command accepts multiple arguments of the same type as the argument before the "..." sequence. The sequence "{..}" is used to represent a set, which is a list of possible arguments to choose from. Builtin Shell Commands bindkey [-l] function string Bindkey is used to customize the shell's command-line editor. Any key on the keyboard can be mapped to any of a number of functions. The various functions are as follows: bindkey Functions Function Meaning backward-char move cursor left backward-delete-char delete character to the left backward-word move cursor left one word beginning-of-line move cursor to beginning of line clear-screen clear screen and redraw prompt complete-word perform filename completion delete-char delete character under cursor down-history replace command line with next history end-of-line move cursor to end of line forward-char move cursor to the right forward-word mvoe cursor one word to the right kill-end-of-line delete line from the cursor to end of line kill-whole-line delete the entire command line list-choices list file completion matches newline finished editing, accept command line raw-char character as-is redisplay redisplay the command line toggle-cursor toggle between insert and overwrite cursor undefined-char this key does nothing up-history replace command line with previous history
Keys are bound to functions, not vice-versa. This means that you can have any number of commands refer to the same function. For example, the default bindings have CTRL-A and OA-< both bound to beginning-of-line. Most of the function names are self-explanatory, and are explained in Chapter 2, but a few deserve discussion. raw-char is what you should bind a key that should be inserted into the command-line as-is. The regular printable ASCII set, such as the letters a-z, numbers, etc. are bound to raw-char. Control characters should not be bound to raw-char because the command-line editor will become confused (most control characters act as special GNO/ME console feature codes - see the GNO Kernel Reference Manual). Any keystroke that should be rejected by the editor should be bound to undefined-char. By default, this includes control characters and OA-sequences that are not assigned to any editing features. Any key bound to undefined-char will cause gsh to beep and ignore the key. You can actually bind key sequences, not just keystrokes, to functions. There is no limit other than memory to how many characters are in a command sequence. Because terminals do not have the OA (Open Apple) key, OA is actually mapped by the kernel to a two-character sequence consisting of ESC and the key. For example, OA-Y would actually produce ESC-Y. Control characters in the string are represented in ^X format; e.g. CTRL-A is represented by ^A. ESC (and OA) is represented by ^[. gno% bindkey kill-end-of-line ^K map Ctrl-K to kill-end-of-line (like Emacs) gno% bindkey clear-screen ^[^X map OA-Clear to clear-screen
commands Displays a list of all built-in shell commands. cd [pathname] chdir [pathname] Changes the current working directory to pathname. If pathname is not given, the default home directory (i.e. the value of the HOME environment variable) is used. This makes it easy to move back to your home directory. Under gsh, unlike most UNIX shells, the cd is not necessary, except to change automatically to your HOME directory. If the first word on the command line is neither a builtin nor an external command, but is instead the name of a directory, a cd is implied and performed on the directory unless the NODIREXEC variable has been set. clear This command takes no arguments. When invoked, the screen will be cleared. dirs See pushd. echo [-n] [arg ...] Expands the "arg" expression(s) and outputs them to the screen. If the -n flag is specified, a newline character is not output after the last arg expression. Special escape sequences may also be included in the arguments, similar to those used in C strings: \b backspace \f form feed (clears screen) \n newline \r carridge return \t tab \nnn a decimal ASCII code exit Exits the shell or terminates a shell script. history This command displays the list of previous command-line entries. The number of entries saved is set in the HISTORY variable. pushd [newdir | +n] popd [+n] dirs These three commands maintain the shell's directory stack. Let's say you're working in a directory /src/myprogs/class/program.1/, and you want to temporarily go to another directory. Instead of having to cd there and cd back to a very long directory name (i.e., lots of typing), you can use the pushd command, like so: gno% pwd /src/myprogs/class/program.1 gno% pushd /etc gno% pwd /etc gno% popd gno% pwd /src/myprogs/class/program.1 The pushd command stores the current directory on a stack, and then changes the current directory to the argument newdir. When you want to go back to the original directory, type popd. The shell will pull the last directory off the stack and make that directory the current directory. If no argument is given, then the current directory is swapped with the directory that is currently on the top of the directory stack. If a digit argument, +n, is given, then the current directory will be swapped with the directory in the nth position on the directory stack. The popd command, when given without an argument, will pop the directory that is on top of the directory stack, and make that directory the current directory. When given an argument of +n, popd will remove the nth directory from the stack. It does not change to that directory. The dirs command displays the current directory stack. pwd Displays the current working directory. This is useful if you have not configured the PROMPT string to print your current working directory. source When a script is executed, gsh creates a new process to run the script. As a result, scripts cannot change the parent shell's environment. Instead of executing the script directly, you may use the source command which does not create a new process to execute the script. Thus, the source command is effectively exactly like typing all the commands in the script from the keyboard. tset The tset command causes the shell to reread the /etc/termcap file and reset its output system to use the terminal type specified in the TERM environment variable. On startup, after reading the gshrc file, gsh automatically does a tset. gsh also automatically does a tset whenever the TERM variable is changed with the set command. You would use tset manually if, for example, a utility changed the value of TERM. which command [...] Let's say that you are working on a new version of the venerable shell utility ls. Since a search of the hash table is done before searching the current directory, you might accidentally be using the wrong version of the command. You make changes and run the new program, but your changes don't seem to appear! Use the which command to check your sanity. Which also comes in handy in locating duplicate program names in the PATH directories (for example, an ls in both /bin and /usr/bin.) The way to access a utility in the current directory which has the same name as a program in the PATH is to prefix the command name with '.', as in './ls'. See also rehash and unhash.
Kernel Commands gsh provides a set of commands to control the GNO kernel. These commands mainly deal with job control. See the chapter on Process Management in the GNO Kernel Reference Manual. bg (%job | pid) Starts the specified job, if stopped, and places it in the background. fg (%job | pid) Starts the specified job, if stopped, and places it in the foreground. jobs [-l] Displays a list of the shell's jobs. If the -l switch is specified, the process id is included in the job list. kill {[-SIGNAL] | %job | pid | [-l] } The kill command will send the signal SIGNAL to the process number pid. The ps command documented below describes how to list all process ID's currently executing. SIGNAL can be either a numeric value or string representing the signal to be sent to the process. All signals are documented in the chapter on Interprocess Communication in the GNO Kernel Reference Manual. Alternatively, specifying the -l option will list all the signals and their names. If the process number isn't known, but the job number is, replace the pid with a '%' followed by the job number. ps This command takes no arguments. When invoked, a list of all currently running processes is displayed: [2] 9:52pm root> ls -lR :hard:gno > /ram5/dev & [1] + 35 Running ls -lR :hard:gno & [3] 9:53pm root> ps ID STATE TT MMID UID TIME COMMAND 1 ready co 1002 0000 0:26 NullProcess 2 ready co 1005 0000 0:02 gsh 35 ready co 100A 0000 0:01 ls -lR :hard:gno 36 running co 1007 0000 0:00 ps [4] 9:53pm root> [1] + Done ls -lR :hard:gno The fields of the ps output are as shown below: ID A unique process ID assigned to a command by GNO. Use this number to reference any process. STATE Current state of the process. Each process can be in any of the following states: RUNNING The process is currently in execution. READY The process is not currently executing, but is ready to be executed as soon as it is assigned a time slice. BLOCKED The process is waiting for a slow I/O operation to complete (for instance, a read from a TTY). NEW The process has been created, but has not executed yet. SUSPENDED The process was stopped with SIGSTOP, SIGTSTP, SIGTTIN, or SIGTTOU. WAITING The process is waiting on a semaphore "signal" operation. Programs waiting for data from a pipe have this state. WAITSIGCH The process is waiting to receive a SIGCHLD signal. PAUSED The process is waiting for any signal. TTY Terminal connected to the process. MMID Memory Manager ID assigned to the process. UID ID of the user who initiated the process. TIME How much CPU time this process has used. This is not the elapsed time of the process. COMMAND Command-line string used to invoke process. setdebug { val | {+|-}flag } Turns GNO kernel debugging code on or off. The value passed consists of a bit field, where each bit specifies a different type of debugging code to activate. An alternate method is to provide a list of debug flags, either preceded by a '+' or a '-'. Those preceded by a '+' are activated, and those preceeded with a '-' are deactivated. All debugging is deactivated by passing a value of 0. Running setdebug wtth no arguments returns a list of the debugging flags. Legal flags include: Kernel Debug Flags Flag Meaning gsostrace Trace GS/OS calls. gsosblocks Trace GS/OS parameter blocks. gsoserrors Trace GS/OS errors. pathtrace Trace GS/OS pathnames. sigtrace Trace signals. systrace Trace GNO Kernel system calls.
stop { %job | pid } Stops the execution of all processes in a specified job.
Environment Commands The last set of commands, environment commands, modify the gsh environment. Many of these commands have been used in other parts of this manual and, therefore, should not be new. alias [name] [value] Creates an alias for a string. When this alias is referenced as a command, value will be expanded into the command line. For commands that require many arguments or have several steps, you could set up an alias to save typing. You can also use aliases to create new names for commands. To obtain a list of all aliases, invoke alias with no arguments. To list the value of a specific alias, invoke alias with name only. export [variable ...] When a shell environment variable is marked as exportable, any process that is created from within the current process (most likely gsh), will be passed copies of the exported variables. See setenv and . hash Displays a list of all commands currently in the shell's hash table; i.e., a list of commands in the various $PATH directories. prefix [prefixnum [prefixname]] GNO maintains a list of 32 'prefixes' for each process. Prefixes allow the user to reference a directory with a number. While gsh provides this ability with environment variables, the prefix command exists to support the ORCA compilers and other utilities that are dependent on certain GS/OS prefixes. contains a list of these prefixes and their "default" meanings, as documented in the "Apple IIgs GS/OS Reference". If refixname is not given, then the value of prefixnum is displayed. If neither argument is given, a list of currently assigned prefixes is displayed. rehash To decrease the time spent searching for a command, gsh builds a hash table of all commands which were found in the pathnames set in the $PATH environment variable. When a command is invoked, only this list is searched. When the $PATH environment variable is changed, gsh must rebuild this list. The rehash command tells gsh to rebuild the list. While the old list is still active, if $PATH is changed and one of the previous search paths is no longer online, gsh will try and execute the command from the offline device, resulting in a command failure. set [var [value]] [...] set value=value [...] setenv [var value] [...] Use these command to create or modify environment variables. If set is invoked with no arguments, a list of the current environment variables is displayed. If only var is given as an argument, the value of var is displayed. To set or reset a variable, use both the var and value arguments. There are two ways to set a variable, either by "var value", or by "var=value". To set multiple variables at once, simply list them all on the command line as shown above. setenv works just like set, but automatically exports the variable(s) or lists only exported variables. When using set or setenv to view a list of variables, exported variable names appear in all capital letters. unalias name [...] To remove an alias from the alias list, use this command. To remove multiple aliases with one command, specify all the aliases on the command line. unhash To disable the internal hash table created with the rehash command, use this command. This is useful if you wish to use only utilities in the current working directory (during testing, for example). unset var [...] To remove a variable from the environment, use unset. unset accepts multiple names if more than one variable is to be deleted. Future attempts to access the variable var will result in an error or a NULL string, depending on the circumstances.