## 5.8. Built-in C Shell Commands

# | `#` Ignore all text that follows on the same line. `#` is used in shell scripts as the comment character and is not really a command. In addition, a file that has `#` as its first character is sometimes interpreted by older systems as a C shell script.
> #! | `#!``shell` [option] Used as the first line of a script to invoke the named shell. Anything given on the rest of the line is passed as a single argument to the named shell. This feature is typically implemented by the kernel, but may not be supported on some older systems. Some systems have a limit of around 32 characters on the maximum length of shell. For example:
>     #!/bin/csh -f
: | `:` Null (do-nothing) command. Returns an exit status of 0.
> alias | `alias` [`name` [command]] Assign name as the shorthand name, or alias, for command. If command is omitted, print the alias for name; if name is also omitted, print all aliases. Aliases can be defined on the command line, but they are more often stored in `.cshrc` so that they take effect after login. (See Section 5.3.4 earlier in this chapter.) Alias definitions can reference command-line arguments, much like the history list. Use `\!*` to refer to all command-line arguments, `\!^` for the first argument, `\!$` for the last, etc. An alias name can be any valid Unix command; however, you lose the original command's meaning unless you type \name. See also unalias. #### Examples Set the size for `xterm` windows under the X Window System:
>     alias R 'set noglob; eval `resize`; unset noglob'
> Show aliases that contain the string ls:
>     alias | grep ls
> Run `nroff` on all command-line arguments:
>     alias ms 'nroff -ms \!*'
> Copy the file that is named as the first argument:
>     alias back 'cp \!^ \!^.old'
> Use the regular `ls`, not its alias:
>     % \ls
> bg | `bg` [`jobIDs`] Put the current job or the jobIDs in the background. See Section 5.6. #### Example To place a time-consuming process in the background, you might begin with:
>     4% nroff -ms report | col > report.txt
>     CTRL-Z
> and then issue any one of the following:
>     5% bg
>     5% bg %         Current job
>     5% bg %1        Job number 1
>     5% bg %nr       Match initial string nroff
>     5% % &
break | `break` Resume execution following the `end` command of the nearest enclosing `while` or `foreach`.
breaksw | `breaksw` Break from a `switch`; continue execution after the `endsw`.
case | `case` `pattern` `:` Identify a pattern in a `switch`.
cd | `cd` [`dir`] Change working directory to dir; default is home directory of user. If dir is a relative pathname but is not in the current directory, the `cdpath` variable is searched. See Section 5.3.4 earlier in this chapter.
chdir | `chdir` [`dir`] Same as `cd`. Useful if you are redefining `cd` as an alias.
continue | `continue` Resume execution of nearest enclosing `while` or `foreach`.
default | `default:` Label the default case (typically last) in a `switch`.
dirs | `dirs` [`-l`] Print the directory stack, showing the current directory first; use `-l` to expand the home directory symbol (`~`) to the actual directory name. See also popd and pushd.
echo | `echo` [`-n`] `string` Write string to standard output; if `-n` is specified, the output is not terminated by a newline. Unlike the Unix version (`/bin/echo`) and the Bourne shell version, the C shell's `echo` doesn't support escape characters. See also echo in Chapter 2 and Chapter 4.
end | `end` Reserved word that ends a `foreach` or `while` statement.
endif | `endif` Reserved word that ends an `if` statement.
endsw | `endsw` Reserved word that ends a `switch` statement.
> eval | `eval` `args` Typically, `eval` is used in shell scripts, and args is a line of code that contains shell variables. `eval` forces variable expansion to happen first and then runs the resulting command. This “double-scanning” is useful any time shell variables contain input/output redirection symbols, aliases, or other shell variables. (For example, redirection normally happens before variable expansion, so a variable containing redirection symbols must be expanded first using `eval`; otherwise, the redirection symbols remain uninterpreted.) A Bourne shell example can be found under eval in Chapter 4. Other uses of `eval` are shown next. #### Examples The following lines can be placed in the `.login` file to set up terminal characteristics:
>     set noglob
>     eval `tset -s xterm`
>     unset noglob
> The following commands show the effect of `eval`:
>     % set b='$a'
>     % set a=hello

>     % echo $b         Read the command line once
>     $a
>     % eval echo $b    Read the command line twice
>     hello
exec | `exec` `command` Execute command in place of current shell. This terminates the current shell, rather than creating a new process under it.
exit | `exit` [`(``expr``)`] Exit a shell script with the status given by expr. A status of 0 means success; nonzero means failure. If expr is not specified, the exit value is that of the `status` variable. `exit` can be issued at the command line to close a window (log out).
> fg | `fg` [`jobIDs`] Bring the current job or the jobIDs to the foreground. See also Section 5.6 earlier in this chapter. #### Example If you suspend a `vi` editing session (by pressing `CTRL-Z`), you might resume `vi` using any of these commands:
>     8% %
>     8% fg
>     8% fg %
>     8% fg %vi    Match initial string
> foreach | `foreach` `name` `(`wordlist`)` commands `end` Assign variable name to each value in wordlist, and execute commands between `foreach` and `end`. You can use `foreach` as a multiline command issued at the C shell prompt (first Example), or you can use it in a shell script (second Example). #### Examples Rename all files that begin with a capital letter:
>     % foreach i ([A-Z]*)
>     ? mv $i $i.new
>     ? end
> Check whether each command-line argument is an option or not:
>     foreach arg ($argv)
>        # does it begin with - ?
>        if ("$arg" =~ -*) then
>           echo "Argument is an option"
>        else
>           echo "Argument is a filename"
>        endif
>     end
glob | `glob` `wordlist` Do filename, variable, and history substitutions on wordlist. This expands it much like `echo`, except that no \ escapes are recognized, and words are delimited by null characters. `glob` is typically used in shell scripts to “hardcode” a value so that it remains the same for the rest of the script.
goto | `goto` `string` Skip to a line whose first nonblank character is string followed by a `:`, and continue execution below that line. On the `goto` line, string can be a variable or filename pattern, but the label branched to must be a literal, expanded value and must not occur within a `foreach` or `while`.
hashstat | `hashstat` Display statistics that show the hash table's level of success at locating commands via the `path` variable.
> history | `history` [`options`] Display the list of history events. (History syntax is discussed earlier in Section 5.5.) Note: multiline compound commands such as `foreach ... end` are not saved in the history list. #### Options `-h` Print history list without event numbers. `-r` Print in reverse order; show oldest commands last. ``n`` Display only the last n history commands, instead of the number set by the `history` shell variable. #### Example To save and execute the last five commands:
>     history -h 5 > do_it
>     source do_it
> if | `if` Begin a conditional statement. The simple format is:
>     if (expr) cmd
> There are three other possible formats, shown side-by-side:
>     if (expr) then   if (expr) then   if (expr) then
>        cmds             cmds1             cmds1
>     endif            else              else if (expr) then
>                         cmds2             cmds2
>                      endif             else
>                                           cmds3
>                                        endif
> In the simplest form, execute cmd if expr is true; otherwise, do nothing (redirection still occurs; this is a bug). In the other forms, execute one or more commands. If expr is true, continue with the commands after `then`; if expr is false, branch to the commands after `else` (or after the `else if` and continue checking). For more examples, see Section 5.4 or shift or while. #### Example Take a default action if no command-line arguments are given:
>     if ($#argv == 0) then
>        echo "No filename given.  Sending to Report."
>        set outfile = Report
>     else
>        set outfile = $argv[1]
>     endif
jobs | `jobs` [`-l`] List all running or stopped jobs; `-l` includes process IDs. For example, you can check whether a long compilation or text format is still running. Also useful before logging out.
> kill | `kill` [``options``] `ID` Terminate each specified process ID or job ID. You must own the process or be a privileged user. This built-in is similar to `/usr/bin/kill` described in Chapter 2 but also allows symbolic job names. Stubborn processes can be killed using signal 9. See also the earlier section “Job Control.” #### Options `-l` List the signal names. (Used by itself.) `-``signal` The signal number (from `/usr/include/sys/signal.h`) or name (from `kill -l`). With a signal number of 9, the kill is absolute. #### Signals Signals are defined in `/usr/include/sys/signal.h` and are listed here without the `SIG` prefix. You probably have more signals on your system than the ones shown here.
>     HUP     1       hangup
>     INT     2       interrupt
>     QUIT    3       quit
>     ILL     4       illegal instruction
>     TRAP    5       trace trap
>     IOT     6       IOT instruction
>     EMT     7       EMT instruction
>     FPE     8       floating point exception
>     KILL    9       kill
>     BUS     10      bus error
>     SEGV    11      segmentation violation
>     SYS     12      bad argument to system call
>     PIPE    13      write to pipe, but no process to read it
>     ALRM    14      alarm clock
>     TERM    15      software termination (the default signal)
>     USR1    16      user-defined signal 1
>     USR2    17      user-defined signal 2
>     CLD     18      child process died
>     PWR     19      restart after power failure
> #### Examples If you've issued the following command:
>     44% nroff -ms report > report.txt &
>     [1] 19536               csh prints job and process IDs
> you can terminate it in any of the following ways:
>     45% kill 19536            Process ID
>     45% kill %                Current job
>     45% kill %1               Job number 1
>     45% kill %nr              Initial string
>     45% kill %?report         Matching string
limit | `limit` [`-h`] [``resource`` [`limit`]] Display limits or set a limit on resources used by the current process and by each process it creates. If no limit is given, the current limit is printed for resource. If resource is also omitted, all limits are printed. By default, the current limits are shown or set; with `-h`, hard limits are used. A hard limit imposes an absolute limit that can't be exceeded. Only a privileged user may raise it. See also unlimit. #### Resource `cputime` Maximum number of seconds the CPU can spend; can be abbreviated as `cpu` `filesize` Maximum size of any one file `datasize` Maximum size of data (including stack) `stacksize` Maximum size of stack `coredumpsize` Maximum size of a core dump file #### Limit A number followed by an optional character (a unit specifier).
For `cputime`: | n `h` (for n hours), n `m` (for n minutes), mm`:``ss` (minutes and seconds).
For others: | n `k` (for n kilobytes, the default), n `m` (for n megabytes).
login | `login` [`user` | `-p` ] Replace user's login shell with `/bin/login`. `-p` preserves environment variables.
logout | `logout` Terminate the login shell.
nice | `nice` [`±``n`] command Change the execution priority for command, or, if none is given, change priority for the current shell. (See also nice in Chapter 2.) The priority range is -20 to 20, with a default of 4. The range is backwards from what you might expect: -20 gives the highest priority (fastest execution); 20 gives the lowest. `+``n` Add n to the priority value (lower job priority). `-``n` Subtract n from the priority value (raise job priority). Privileged users only.
nohup | `nohup` [`command`] “No hangup signals.” Do not terminate command after terminal line is closed (i.e., when you hang up from a phone or log out). Use without command in shell scripts to keep script from being terminated. (See also nohup in Chapter 2.)
notify | `notify` [`jobID`] Report immediately when a background job finishes (instead of waiting for you to exit a long editing session, for example). If no jobID is given, the current background job is assumed.
> onintr | `onintr` `label` `onintr -` `onintr` “On interrupt.” Used in shell scripts to handle interrupt signals (similar to the Bourne shell's `trap 2` and `trap "" 2` commands). The first form is like a `goto` label. The script branches to label`:` if it catches an interrupt signal (e.g., `CTRL-C`). The second form lets the script ignore interrupts. This is useful at the beginning of a script or before any code segment that needs to run unhindered (e.g., when moving files). The third form restores interrupt handling that was previously disabled with `onintr -`. #### Example
>     onintr cleanup     Go to “cleanup” on interrupt
>      .
>      .                 Shell script commands
>      .
>     cleanup:           Label for interrupts
>       onintr -         Ignore additional interrupts
>       rm -f $tmpfiles  Remove any files created
>       exit 2           Exit with an error status
popd | `popd` [`+``n`] Remove the current entry from the directory stack or remove the nth entry from the stack. The current entry has number 0 and appears on the left. See also dirs and pushd.
> pushd | `pushd` `name` `pushd` `+`n `pushd` The first form changes the working directory to name and adds it to the directory stack. The second form rotates the nth entry to the beginning, making it the working directory. (Entry numbers begin at 0.) With no arguments, `pushd` switches the first two entries and changes to the new current directory. See also dirs and popd. #### Examples
>     5% dirs
>     /home/bob /usr
>     6% pushd /etc             Add /etc to directory stack
>     /etc /home/bob /usr
>     7% pushd +2               Switch to third directory
>     /usr /etc /home/bob
>     8% pushd                  Switch top two directories
>     /etc /usr /home/bob
>     9% popd                   Discard current entry; go to next
>     /usr /home/bob
rehash | `rehash` Recompute the hash table for the `path` variable. Use `rehash` whenever a new command is created during the current session. This allows the shell to locate and execute the command. (If the new command resides in a directory not listed in `path`, add this directory to `path` before rehashing.) See also unhash.
> repeat | `repeat` `n command` Execute n instances of command. #### Examples Generate a test file for a program by saving 25 copies of `/usr/dict/words` in a file:
>     % repeat 25 cat /usr/dict/words > test_file
> Read 10 lines from the terminal and store in `item_list`:
>     % repeat 10 line > item_list
> Append 50 boilerplate files to `report`:
>     % repeat 50 cat template >> report
> set | `set` `variable` `=` value `set` variable`[`n`] =` value `set` Set variable to value, or, if multiple values are specified, set the variable to the list of words in the value list. If an index n is specified, set the nth word in the variable to value. (The variable must already contain at least that number of words.) With no arguments, display the names and values of all set variables. See also Section 5.3.3 earlier in this chapter. #### Examples
>     % set list=(yes no maybe)           Assign a word list
>     % set list[3]=maybe                 Assign an item in existing word list
>     % set quote="Make my day"           Assign a variable
>     % set x=5 y=10 history=100          Assign several variables
>     % set blank                         Assign a null value to blank
setenv | `setenv` [`name` [value]] Assign a value to an environment variable name. By convention, name should be uppercase. value can be a single word or a quoted string. If no value is given, the null value is assigned. With no arguments, display the names and values of all environment variables. `setenv` is not necessary for the USER, TERM, and PATH variables because they are automatically exported from `user`, `term`, and `path`. See also Section 5.3.5.
> shift | `shift` [`variable`] If variable is given, shift the words in a word list variable; i.e., name`[2]` becomes name`[1]`. With no argument, shift the positional parameters (command-line arguments); i.e., `$2` becomes `$1`. `shift` is typically used in a `while` loop. See additional Example under while. #### Example
>     while ($#argv)      While there are arguments
>         if (-f $argv[1])
>            wc -l $argv[1]
>         else
>            echo "$argv[1] is not a regular file"
>         endif
>         shift           Get the next argument
>     end
> source | `source` [`-h`] `script` Read and execute commands from a C shell script. With `-h`, the commands are added to the history list but aren't executed. #### Example
>     source ~/.cshrc
stop | `stop` [`jobIDs`] Suspend the current background job or the background job specified by jobIDs; this is the complement of `CTRL-Z` or `suspend`.
suspend | `suspend` Suspend the current foreground job; similar to `CTRL-Z`. Often used to stop an `su` command.
> switch | `switch` Process commands depending on the value of a variable. When you need to handle more than three choices, `switch` is a useful alternative to an `if-then-else` statement. If the string variable matches pattern1, the first set of commands is executed; if string matches pattern2, the second set of commands is executed; and so on. If no patterns match, execute commands under the `default` case. string can be specified using command substitution, variable substitution, or filename expansion. Patterns can be specified using pattern-matching symbols `*`, `?`, and `[` `]`. `breaksw` exits the `switch` after commands are executed. If `breaksw` is omitted (which is rarely done), the `switch` continues to execute another set of commands until it reaches a `breaksw` or `endsw`. Here is the general syntax of `switch`, side-by-side with an example that processes the first command-line argument.
>     switch (string)    switch ($argv[1])
>       case pattern1:      case -[nN]:
>           commands            nroff $file | lp
>           breaksw             breaksw
>       case pattern2:      case -[Pp]:
>           commands            pr $file | lp
>           breaksw             breaksw
>       case pattern3:      case -[Mm]:
>           commands            more $file
>           breaksw             breaksw
>           .                case -[Ss]:
>           .                    sort $file
>           .                    breaksw
>       default:             default:
>           commands             echo "Error-no such option"
>                                exit 1
>           breaksw              breaksw
>     endsw                 endsw
time | `time` [`command`] Execute a command and show how much time it uses. With no argument, `time` can be used in a shell script to time it.
umask | `umask` [`nnn`] Display file-creation mask or set file creation mask to octal nnn. The file-creation mask determines which permission bits are turned off. See the entry in Chapter 2 for examples.
unalias | `unalias` `name` Remove name from the alias list. See alias for more information.
unhash | `unhash` Remove internal hash table. The C shell stops using hashed values and spends time searching the `path` directories to locate a command. See also rehash.
unlimit | `unlimit` [`resource`] Remove the allocation limits on resource. If resource is not specified, remove limits for all resources. See limit for more information.
unset | `unset` `variables` Remove one or more variables. Variable names may be specified as a pattern, using filename metacharacters. See set.
unsetenv | `unsetenv` `variable` Remove an environment variable. Filename matching is not valid. See setenv.
wait | `wait` Pause in execution until all background jobs complete, or until an interrupt signal is received.
> while | `while (``expression``)` commands `end` As long as expression is true (evaluates to nonzero), evaluate commands between `while` and `end`. `break` and `continue` can terminate or continue the loop. See also the Example under shift. #### Example
>     set user = (alice bob carol ted)
>     while ($argv[1] != $user[1])
>        Cycle through each user, checking for a match
>        shift user
>        If we cycled through with no match...
>        if ($#user == 0) then
>          echo "$argv[1] is not on the list of users"
>          exit 1
>        endif
>     end
@ | `@` `variable` `=` expression `@` variable`[`n`] =` expression `@` Assign the value of the arithmetic expression to variable, or to the nth element of variable if the index n is specified. With no variable or expression specified, print the values of all shell variables (same as `set`). Expression operators as well as examples are listed in Section 5.4. Two special forms are also valid: `@` `variable``++` Increment variable by one. `@` `variable``--` Decrement variable by one.

Copyright © 2003 O'Reilly & Associates. All rights reserved.