Bourne | Ash |  #!  | find | ARG_MAX | Shells | portability | permissions | UUOC | - | ../Various | HOME
"$@" | echo/printf | set -e | test | tty defs | tty chars | $() vs ) | IFS | using siginfo | nanosleep | line charset | locale


Manual of the Bourne Shell on SVR1

original sh.1 massaged, nroffed and htmlized.


SH(1)                                                                    SH(1)



NAME
       sh, rsh - shell, the standard/restricted command programming language

SYNOPSIS
       sh [ -ceiknrstuvx ] [ args ]
       rsh [ -ceiknrstuvx ] [ args ]

DESCRIPTION
       Sh is a command programming language that executes commands read from a
       terminal or a file.  Rsh is a restricted version of the  standard  com-
       mand  interpreter  sh;  it  is used to set up login names and execution
       environments whose capabilities are more controlled than those  of  the
       standard  shell.   See Invocation below for the meaning of arguments to
       the shell.

   Commands.
       A simple-command is a sequence of non-blank words separated  by  blanks
       (a  blank  is  a tab or a space).  The first word specifies the name of
       the command to be executed.  Except as specified below,  the  remaining
       words are passed as arguments to the invoked command.  The command name
       is passed as argument 0 (see exec(2)).  The value of  a  simple-command
       is  its exit status if it terminates normally, or (octal) 200+status if
       it terminates abnormally (see signal(2) for a list of status values).

       A pipeline is a sequence of one or more commands separated  by  |  (or,
       for  historical compatibility, by ^).  The standard output of each com-
       mand but the last is connected by a pipe(2) to the  standard  input  of
       the next command.  Each command is run as a separate process; the shell
       waits for the last command to terminate.

       A list is a sequence of one or more pipelines separated by ;, &, &&, or
       ||,  and optionally terminated by ; or &.  Of these four symbols, ; and
       & have equal precedence, which is lower than that of &&  and  ||.   The
       symbols  &&  and || also have equal precedence.  A semicolon (;) causes
       sequential execution of the preceding pipeline; an ampersand (&) causes
       asynchronous  execution of the preceding pipeline (i.e., the shell does
       not wait for that pipeline to finish).  The symbol && (||)  causes  the
       list following it to be executed only if the preceding pipeline returns
       a zero (non-zero) exit status.  An arbitrary number  of  new-lines  may
       appear in a list, instead of semicolons, to delimit commands.

       A  command  is either a simple-command or one of the following.  Unless
       otherwise stated, the value returned by a command is that of  the  last
       simple-command executed in the command.

       for name [ in word ... ] do list done
              Each  time  a  for  command is executed, name is set to the next
              word taken from the in word list.  If in word ...   is  omitted,
              then  the  for  command executes the do list once for each posi-
              tional parameter that is set (see Parameter Substitution below).
              Execution ends when there are no more words in the list.
       case word in [ pattern [ | pattern ] ... ) list ;; ] ... esac
              A  case command executes the list associated with the first pat-
              tern that matches word.  The form of the patterns is the same as
              that  used  for  file-name  generation (see File Name Generation
              below).
       if list then list [ elif list then list ] ... [ else list ] fi
              The list following if is executed and, if it returns a zero exit
              status,  the  list following the first then is executed.  Other-
              wise, the list following elif is executed and, if its  value  is
              zero,  the  list  following  the next then is executed.  Failing
              that, the else list is executed.  If no else list or  then  list
              is executed, then the if command returns a zero exit status.
       while list do list done
              A  while  command repeatedly executes the while list and, if the
              exit status of the last command in the list  is  zero,  executes
              the  do  list; otherwise the loop terminates.  If no commands in
              the do list are executed, then the while command returns a  zero
              exit  status;  until may be used in place of while to negate the
              loop termination test.
       (list)
              Execute list in a sub-shell.
       {list;}
              list is simply executed.

       The following words are only recognized as the first word of a  command
       and when not quoted:

       if then else elif fi case esac for while until do done { }

   Comments.
       A  word beginning with # causes that word and all the following charac-
       ters up to a new-line to be ignored.

   Command Substitution.
       The standard output from a command enclosed in a pair of grave  accents
       (``)  may  be  used  as  part  or all of a word; trailing new-lines are
       removed.

   Parameter Substitution.
       The character $ is used to introduce substitutable  parameters.   Posi-
       tional  parameters may be assigned values by set.  Variables may be set
       by writing:

              name=value [ name=value ] ...

       Pattern-matching is not performed on value.

       ${parameter}
              A parameter is a sequence of letters, digits, or underscores  (a
              name),  a  digit, or any of the characters *, @, #, ?, -, $, and
              !.  The value, if any, of the  parameter  is  substituted.   The
              braces are required only when parameter is followed by a letter,
              digit, or underscore that is not to be interpreted  as  part  of
              its  name.   A  name must begin with a letter or underscore.  If
              parameter is a digit then it  is  a  positional  parameter.   If
              parameter  is * or @, then all the positional parameters, start-
              ing with $1, are substituted (separated by  spaces).   Parameter
              $0 is set from argument zero when the shell is invoked.
       ${parameter:-word}
              If  parameter  is set and is non-null then substitute its value;
              otherwise substitute word.
       ${parameter:=word}
              If parameter is not set or is null then  set  it  to  word;  the
              value  of the parameter is then substituted.  Positional parame-
              ters may not be assigned to in this way.
       ${parameter:?word}
              If parameter is set and is non-null then substitute  its  value;
              otherwise, print word and exit from the shell.  If word is omit-
              ted, then the message ``parameter null or not set'' is  printed.
       ${parameter:+word}
              If parameter is set and is non-null then substitute word; other-
              wise substitute nothing.

       In the above, word is not evaluated unless it is to be used as the sub-
       stituted  string,  so  that,  in the following example, pwd is executed
       only if d is not set or is null:

              echo ${d:-`pwd`}

       If the colon (:) is omitted from the above expressions, then the  shell
       only checks whether parameter is set or not.

       The following parameters are automatically set by the shell:
              #      The number of positional parameters in decimal.
              -      Flags  supplied  to the shell on invocation or by the set
                     command.
              ?      The decimal value returned by the last synchronously exe-
                     cuted command.
              $      The process number of this shell.
              !      The   process  number  of  the  last  background  command
                     invoked.

       The following parameters are used by the shell:
              HOME   The default argument (home directory) for the cd command.
              PATH   The  search path for commands (see Execution below).  The
                     user may not change PATH if executing under rsh.
              CDPATH The search path for the cd command.
              MAIL   If this variable is set to the name of a mail file,  then
                     the  shell informs the user of the arrival of mail in the
                     specified file.
              PS1    Primary prompt string, by default ``$ ''.
              PS2    Secondary prompt string, by default ``> ''.
              IFS    Internal field separators, normally space, tab, and  new-
                     line.

       The  shell  gives default values to PATH, PS1, PS2, and IFS, while HOME
       and MAIL are not set at all by the  shell  (although  HOME  is  set  by
       login(1)).

   Blank Interpretation.
       After  parameter  and command substitution, the results of substitution
       are scanned for internal field separator  characters  (those  found  in
       IFS) and split into distinct arguments where such characters are found.
       Explicit null arguments ("" or '') are retained.  Implicit  null  argu-
       ments  (those  resulting  from  parameters  that  have  no  values) are
       removed.

   File Name Generation.
       Following substitution, each command word is scanned for the characters
       *,  ?,  and  [.   If  one  of these characters appears then the word is
       regarded as a pattern.  The word is replaced with alphabetically sorted
       file  names  that  match  the  pattern.   If no file name is found that
       matches the pattern, then the word is left unchanged.  The character  .
       at  the  start  of a file name or immediately following a /, as well as
       the character / itself, must be matched explicitly.

              *      Matches any string, including the null string.
              ?      Matches any single character.
              [...]  Matches any one of the enclosed characters.   A  pair  of
                     characters separated by - matches any character lexically
                     between the pair, inclusive.  If the first character fol-
                     lowing  the  opening ``[ is a ``!''  then any character
                     not enclosed is matched.

   Quoting.
       The following characters have a special meaning to the shell and  cause
       termination of a word unless quoted:

              ;  &  (  )  |  ^  <  >  new-line  space  tab

       A character may be quoted (i.e., made to stand for itself) by preceding
       it with a \.  The pair \new-line is ignored.  All  characters  enclosed
       between  a  pair of single quote marks (''), except a single quote, are
       quoted.  Inside double quote marks (""), parameter and command  substi-
       tution  occurs  and  \  quotes  the characters \, `, ", and $.  "$*" is
       equivalent to "$1 $2 ...", whereas "$@" is equivalent to "$1" "$2" ....

   Prompting.
       When used interactively, the shell prompts with the value of PS1 before
       reading a command.  If at any time a  new-line  is  typed  and  further
       input is needed to complete a command, then the secondary prompt (i.e.,
       the value of PS2) is issued.

   Input/Output.
       Before a command is executed, its input and output  may  be  redirected
       using  a  special notation interpreted by the shell.  The following may
       appear anywhere in a simple-command or may precede or follow a  command
       and  are  not  passed  on  to  the invoked command; substitution occurs
       before word or digit is used:

       <word         Use file word as standard input (file descriptor 0).
       >word         Use file word as standard output (file descriptor 1).  If
                     the file does not exist then it is created; otherwise, it
                     is truncated to zero length.
       >>word        Use file word as standard output.   If  the  file  exists
                     then  output  is  appended to it (by first seeking to the
                     end-of-file); otherwise, the file is created.
       <<[-]word     The shell input is read up to a line that is the same  as
                     word,  or  to  an  end-of-file.   The  resulting document
                     becomes the standard input.  If any character of word  is
                     quoted, then no interpretation is placed upon the charac-
                     ters of the document; otherwise,  parameter  and  command
                     substitution  occurs,  (unescaped)  \new-line is ignored,
                     and \ must be used to quote the characters \, $,  `,  and
                     the  first  character  of  word.  If - is appended to <<,
                     then all leading tabs are stripped from word and from the
                     document.
       <&digit       The  standard  input  is  duplicated from file descriptor
                     digit (see dup(2)).  Similarly for  the  standard  output
                     using >.
       <&-           The standard input is closed.  Similarly for the standard
                     output using >.

       If one of the above is preceded by a digit, then  the  file  descriptor
       created is that specified by the digit (instead of the default 0 or 1).
       For example:

              ... 2>&1

       creates file descriptor 2 that is a duplicate of file descriptor 1.

       If a command is followed by & then the default standard input  for  the
       command  is  the  empty file /dev/null.  Otherwise, the environment for
       the execution of a command contains the file descriptors of the  invok-
       ing shell as modified by input/output specifications.

       Redirection of output is not allowed in the restricted shell.

   Environment.
       The  environment (see environ(5)) is a list of name-value pairs that is
       passed to an executed program in the same  way  as  a  normal  argument
       list.   The  shell  interacts with the environment in several ways.  On
       invocation, the shell scans the environment and creates a parameter for
       each  name found, giving it the corresponding value.  Executed commands
       inherit the same environment.  If the user modifies the values of these
       parameters  or  creates new ones, none of these affects the environment
       unless the export command is used to bind the shell's parameter to  the
       environment.  The environment seen by any executed command is thus com-
       posed of any unmodified name-value pairs originally  inherited  by  the
       shell,  plus any modifications or additions, all of which must be noted
       in export commands.

       The environment for any simple-command may be augmented by prefixing it
       with one or more assignments to parameters.  Thus:

              TERM=450 cmd args                  and
              (export TERM; TERM=450; cmd args)

       are equivalent (as far as the above execution of cmd is concerned).

       If the -k flag is set, all keyword arguments are placed in the environ-
       ment, even if they occur after the command name.  The  following  first
       prints a=b c and then c:

              echo a=b c
              set -k
              echo a=b c

   Signals.
       The  INTERRUPT  and  QUIT signals for an invoked command are ignored if
       the command is followed by &; otherwise signals have the values  inher-
       ited by the shell from its parent, with the exception of signal 11 (but
       see also the trap command below).

   Execution.
       Each time a command is executed, the above  substitutions  are  carried
       out.   Except  for  the Special Commands listed below, a new process is
       created and an attempt is made to execute the command via exec(2).

       The shell parameter PATH defines the search path for the directory con-
       taining  the  command.   Alternative directory names are separated by a
       colon (:).  The default path is :/bin:/usr/bin (specifying the  current
       directory,  /bin,  and /usr/bin, in that order).  Note that the current
       directory is specified by a null path name, which  can  appear  immedi-
       ately  after  the  equal  sign or between the colon delimiters anywhere
       else in the path list.  If the command  name  contains  a  /  then  the
       search  path  is  not  used;  such commands will not be executed by the
       restricted shell.  Otherwise, each directory in the  path  is  searched
       for  an executable file.  If the file has execute permission but is not
       an a.out file, it is assumed to be a file containing shell commands.  A
       sub-shell  (i.e.,  a separate process) is spawned to read it.  A paren-
       thesized command is also executed in a sub-shell.

   Special Commands.
       The following commands are executed in the shell process and, except as
       specified, no input/output redirection is permitted for such commands:

       :      No  effect;  the  command  does  nothing.   A  zero exit code is
              returned.
       . file Read and execute commands from file and return.  The search path
              specified by PATH is used to find the directory containing file.
       break [ n ]
              Exit from the enclosing for or while loop,  if  any.   If  n  is
              specified then break n levels.
       continue [ n ]
              Resume  the  next  iteration of the enclosing for or while loop.
              If n is specified then resume at the n-th enclosing loop.
       cd [ arg ]
              Change the current directory to arg.  The shell  parameter  HOME
              is  the  default  arg.   The  shell parameter CDPATH defines the
              search path  for  the  directory  containing  arg.   Alternative
              directory  names are separated by a colon (:).  The default path
              is <null> (specifying the current  directory).   Note  that  the
              current  directory  is  specified by a null path name, which can
              appear immediately after the equal sign  or  between  the  colon
              delimiters anywhere else in the path list.  If arg begins with a
              / then the search path is not used.  Otherwise,  each  directory
              in the path is searched for arg.  The cd command may not be exe-
              cuted by rsh.
       eval [ arg ... ]
              The arguments are read as input to the shell and  the  resulting
              command(s) executed.
       exec [ arg ... ]
              The  command  specified by the arguments is executed in place of
              this shell without creating a new process.   Input/output  argu-
              ments may appear and, if no other arguments are given, cause the
              shell input/output to be modified.
       exit [ n ]
              Causes a shell to exit with the exit status specified by n.   If
              n  is  omitted  then the exit status is that of the last command
              executed (an end-of-file will also cause the shell to exit.)
       export [ name ... ]
              The given names are marked for automatic export to the  environ-
              ment  of  subsequently-executed  commands.   If no arguments are
              given, then a list of all names that are exported in this  shell
              is printed.
       newgrp [ arg ... ]
              Equivalent to exec newgrp arg ....
       read [ name ... ]
              One  line  is read from the standard input and the first word is
              assigned to the first name, the second word to the second  name,
              etc., with leftover words assigned to the last name.  The return
              code is 0 unless an end-of-file is encountered.
       readonly [ name ... ]
              The given names are marked readonly and the values of the  these
              names  may not be changed by subsequent assignment.  If no argu-
              ments are given, then a list of all readonly names is printed.
       set [ --ekntuvx [ arg ... ] ]
              -e     Exit immediately if a command exits with a non-zero  exit
                     status.
              -k     All keyword arguments are placed in the environment for a
                     command, not just those that precede the command name.
              -n     Read commands but do not execute them.
              -t     Exit after reading and executing one command.
              -u     Treat unset variables as an error when substituting.
              -v     Print shell input lines as they are read.
              -x     Print commands and their arguments as they are  executed.
              --     Do  not  change any of the flags; useful in setting $1 to
                     -.
              Using + rather than - causes  these  flags  to  be  turned  off.
              These  flags can also be used upon invocation of the shell.  The
              current set of flags may be found in $-.   The  remaining  argu-
              ments  are  positional parameters and are assigned, in order, to
              $1, $2, ....  If no arguments are given then the values  of  all
              names are printed.
       shift [ n ]
              The positional parameters from $n+1 ...  are renamed $1 ....  If
              n is not given, it is assumed to be 1.
       test
              Evaluate conditional expressions.  See  test(1)  for  usage  and
              description.
       times
              Print  the  accumulated  user and system times for processes run
              from the shell.
       trap [ arg ] [ n ] ...
              arg is a command to be read and executed when the shell receives
              signal(s)  n.   (Note  that arg is scanned once when the trap is
              set and once when the trap is taken.)  Trap  commands  are  exe-
              cuted in order of signal number.  Any attempt to set a trap on a
              signal that was ignored on entry to the current shell  is  inef-
              fective.   An  attempt  to  trap  on  signal  11  (memory fault)
              produces an error.  If arg is absent  then  all  trap(s)  n  are
              reset  to their original values.  If arg is the null string then
              this signal is ignored by the  shell  and  by  the  commands  it
              invokes.   If  n  is  0 then the command arg is executed on exit
              from the shell.  The trap command with  no  arguments  prints  a
              list of commands associated with each signal number.
       ulimit [ -fp ] [ n ]
              imposes a size limit of n
              -f     imposes  a  size  limit  of  n blocks on files written by
                     child processes (files of any size may be read).  With no
                     argument, the current limit is printed.
              -p     changes the pipe size to n (UNIX System/RT only).
              If no option is given, -f is assumed.
       umask [ nnn ]
              The  user  file-creation  mask is set to nnn (see umask(2)).  If
              nnn is omitted, the current value of the mask is printed.
       wait [ n ]
              Wait for the specified process and report its  termination  sta-
              tus.   If  n  is  not given then all currently active child pro-
              cesses are waited for and the return code is zero.


   Invocation.
       If the shell is invoked through exec(2)  and  the  first  character  of
       argument  zero  is -, commands are initially read from /etc/profile and
       then from $HOME/.profile, if such files  exist.   Thereafter,  commands
       are  read  as described below, which is also the case when the shell is
       invoked as /bin/sh.  The flags below are interpreted by  the  shell  on
       invocation  only;  Note that unless the -c or -s flag is specified, the
       first argument is assumed to be the name of a file containing commands,
       and the remaining arguments are passed as positional parameters to that
       command file:

       -c string If the -c flag is present then commands are read from string.
       -s        If the -s flag is present or if no arguments remain then com-
                 mands are read from the standard input.  Any remaining  argu-
                 ments  specify  the  positional  parameters.  Shell output is
                 written to file descriptor 2.
       -i        If the -i flag is present or if the shell  input  and  output
                 are  attached  to a terminal, then this shell is interactive.
                 In this case TERMINATE is ignored (so that kill  0  does  not
                 kill  an  interactive  shell)  and  INTERRUPT  is  caught and
                 ignored (so that wait is interruptible).  In all cases,  QUIT
                 is ignored by the shell.
       -r        If the -r flag is present the shell is a restricted shell.

       The  remaining  flags and arguments are described under the set command
       above.

   Rsh Only.
       Rsh is used to set up login  names  and  execution  environments  whose
       capabilities are more controlled than those of the standard shell.  The
       actions of rsh are identical to those of sh, except that the  following
       are disallowed:
              changing directory (see cd(1)),
              setting the value of $PATH,
              specifying path or command names containing /,
              redirecting output (> and >>).

       The restrictions above are enforced after .profile is interpreted.

       When  a  command  to  be executed is found to be a shell procedure, rsh
       invokes sh to execute it.  Thus, it is possible to provide to the  end-
       user  shell  procedures that have access to the full power of the stan-
       dard shell, while imposing a limited  menu  of  commands;  this  scheme
       assumes  that  the end-user does not have write and execute permissions
       in the same directory.

       The net effect of these rules is that the writer of  the  .profile  has
       complete  control  over  user  actions,  by performing guaranteed setup
       actions and leaving the user in an appropriate directory (probably  not
       the login directory).

       The  system  administrator often sets up a directory of commands (i.e.,
       /usr/rbin) that can be safely invoked by rsh.  Some systems  also  pro-
       vide a restricted editor red.

EXIT STATUS
       Errors detected by the shell, such as syntax errors, cause the shell to
       return a non-zero exit status.  If the shell is being used non-interac-
       tively  then  execution of the shell file is abandoned.  Otherwise, the
       shell returns the exit status of the last command  executed  (see  also
       the exit command above).

FILES
       /etc/profile
       $HOME/.profile
       /tmp/sh*
       /dev/null

SEE ALSO
       cd(1), env(1), login(1), newgrp(1), test(1), umask(1), dup(2), exec(2),
       fork(2), pipe(2), signal(2), ulimit(2),  umask(2),  wait(2),  a.out(4),
       profile(4), environ(5).

BUGS
       The  command  readonly  (without arguments) produces the same output as
       the command export.
       If << is used to provide standard  input  to  an  asynchronous  process
       invoked  by &, the shell gets mixed up about naming the input document;
       a garbage file /tmp/sh* is created and the shell  complains  about  not
       being able to find that file by another name.