Chapter 4

Built-in Commands

Built-ins vs EXE 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.

Shell Commands

Shell built-ins provide support for external shell commands (i.e. EXE files and shell scripts) and provide some commands used in every-day work.

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:

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, Chapter 4 TextTools Replacement).

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, ; 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 ^[.

Examples:

% bindkey kill-end-of-line ^K map CTRL-K to kill-end-of-line (like Emacs)

% 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 a command is not a built-in or EXE file, but is instead the name of a directory, a cd is implied and performed on the directory unless the NODIREXEC variable has been set.

[1] gno> cd utilities

[2] gno/utilities> echo $HOME

/dev/gno

[3] gno/utilities> cd

[4] gno> utilities

[5] gno/utilities> ../utilities

[6] gno/utilities> ~

[7] gno> _

clear

This command takes no arguments. When invoked, the screen will be cleared.

df

This command takes no arguments. When invoked, a listing of free blocks for every block device is given. In addition, the device name, type, file system, and capacity is listed.

[1] gno> df

.d## Volume Device Free Total Capacity System

---- ---------------- ---------------- ------- ------- -------- -----------

.d1 :Procyon .CVTECH.S6.A 3166 41037 92% ProDOS

.d2 Apple 3.5 Drive .APPLEDISK3.5A

.d3 Apple 3.5 Drive .APPLEDISK3.5B

.d4 Console Driver .CONSOLE

.d5 :Day .CVTECH.S6.B 15881 65535 75% ProDOS

.d6 :Night .CVTECH.S6.C 39274 65535 40% HFS

.d7 :Left .CVTECH.S6.D 5365 51776 89% ProDOS

.d8 :Right .CVTECH.S6.E 27477 65535 58% ProDOS

.d9 :Software .CVTECH.S6.F 3289 40960 91% ProDOS

.d10 :RAM5 .RAMDISK 505 512 1% ProDOS

.d11 :Conner 40 .AFP1 7368 80604 90% AppleShare

.d12 AppleTalk fsd .AFP2

....

.d24 AppleTalk fsd .AFP14

.d25 AppleTalk RPM .RPM

.d26 AppleTalk Main .APPLETALK

.d27 Serial Modem .SERIAL2

.d28 :system .APPLESCSI.HD01. 27561 50773 45% ProDOS

.d29 :dev .APPLESCSI.HD01. 43431 65108 33% ProDOS

.d30 :usr .APPLESCSI.HD01. 44376 48725 8% ProDOS

Volume - Name of device.

Device - GS/OS device name.

Free - Total number of free blocks on device.

Total - Total number of blocks on device.

Capacity - Percentage of used blocks on device.

System - Format of file system. With System Software 6.0.1, the file systems available are ProDOS, HFS, Pascal, MS-DOS, and DOS 3.3, and some CD-ROM formats.

echo [-n] arg [arg ...]

Expands the "arg" expression(s) and outputs them to the screen. If the "-n" switch 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 - Clears screen (form feed)

\n - Newline

\r - Return

\t - Tab

\nnn - A decimal ASCII code. nnn represents the ASCII code.

[1] gno> echo Hello World

Hello World

[2] gno> echo -n Hello World

Hello World[3] gno> echo $PATH $HOME 'come get to $gnome'

/dev/gno/utilities /dev/orca/utilities /dev/gno come get to $gnome

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

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:

gsh> pushd /etc { start in /src/myprogs/class/program.1/ }

...

gsh> popd { back in /src/myprogs/class/program.1/ }

The pushd command stores the current directory on a stack, and then changes the current directory to the argument. When you want to go back to the original directory, type popd. The shell will pull the last directory off the stack and 'cd' to that directory.

The popd command when given an argument of +n will remove the n'th 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 output your current working directory.

[1]> cd $HOME

[2]> pwd

/user/root

[3]> cd utilities

[4]> pwd

/user/root/utilities

source

When a script is executed, gsh creates a new process to run the script. As a result, scripts cannot change the shell's prefixes and certain other parameters. 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 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_name [command_name ...]

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". Also, see unhash.

Kernel Commands

gsh provides a set of commands to control the GNO kernel. These commands mainly deal with job control. See Chapter 3 Job Control.

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 brings it into 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.

[1] gno> cmpl foo.c keep=foo &

[1] + Running cmpl foo.c keep=foo &

[2] gno> echo hello

hello

[3] gno> jobs

[1] + Running cmpl foo.c keep=foo &

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 Appendix D Signals, with numeric and string value listed. 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

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:

TTY - Terminal connected to process.

MMID - Memory Manager ID assigned to 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:

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 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 an alias, invoke alias with name only. Here are some alias examples:

Alias Command Name

ll or list_long ls -l

backup_sys cp -r /system /BackupDrive&

backup_home cp -r $HOME /BackupDrive&

print echo

catalog ls -l

delete rm

copy cp

type more

rename mv

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 Chapter 5 Scope of shell variables.

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. Appendix B contains a list of these prefixes and their "default" meanings, as documented in the "Apple IIGS GS/OS Reference", Volume 1.

If prefixname is not given, 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 table of all commands which were found in the pathnames set in the $PATH variable. When a command is invoked, only this list is searched. When the $PATH 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.

To make this a one-step process, the change.path shell script listed in Chapter 5, Accessing shell variables can be used.

set [var] [value] [{var value} ...]

set var=value [var=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 "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 variables appear in ALL CAPS.

unalias name [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 [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.

[8] 9:57pm root> set

PAGER = less

PATH = :hard:gno:bin :right:gno:usr:bin

user1 = foo

USRMAN = /usr/man

HISTORY = 30

status = 227

fignore = .a .root .sym

TERM = gnocon

LESS = -e

PROMPT = [%h] %S%t%s %C>

HOME = :hard:gno:user:root

user = user1

nonewline = 1

[9] 9:57pm root> unset user1

[10] 9:57pm root> unset user

[11] 9:57pm root> set

PAGER = less

PATH = :hard:gno:bin :right:gno:usr:bin

USRMAN = /usr/man

HISTORY = 30

status = 0

fignore = .a .root .sym

TERM = gnocon

LESS = -e

PROMPT = [%h] %S%t%s %C>

HOME = :hard:gno:user:root

nonewline = 1