Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
sh(1)			    General Commands Manual			 sh(1)

       sh,  for, case, if, while, :, .,	break, continue, cd, eval, exec, exit,
       export, login, read, readonly, set, shift, times, trap, umask,  wait  -
       command language

       sh [ -ceiknrstuvx ] [ arg...  ]

       The  command  is	 a command programming language	that executes commands
       read from a terminal or a file.	See Invocation for the meaning of  ar-
       guments to the shell.

       A simple	command	is a sequence of nonblank 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.  For further information, see The value of	a sim-
       ple command is its exit status if it terminates normally	or  200+status
       if it terminates	abnormally.  For a list	of status values, see

       A  pipeline  is a sequence of one or more commands separated by |.  The
       standard	output of each command but the last is connected by a  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 &.	 ; and & have equal precedence
       which is	lower than that	of && and ||, && and ||	also have equal	prece-
       dence.	A  semicolon causes sequential execution.  An ampersand	causes
       the preceding pipeline to be executed without waiting for it to finish.
       The symbol && (||) causes the list following to be executed only	if the
       preceding pipeline returns a zero (nonzero) value.  Newlines may	appear
       in a list, instead of semicolons, to delimit commands.

       A  command  is  either  a  simple command or one	of the following.  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 in the for word list.  If in	word ...  is omitted, in  "$@"
	      is  assumed.  Execution ends when	there are no more words	in the

       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.

       if list then list [ elif	list then list ] ... [ else list ] fi
	      The list following if is executed	and if it  returns  zero,  the
	      list  following then is executed.	 Otherwise, the	list following
	      elif is executed and if its value	is zero,  the  list  following
	      then is executed.	 Failing that, the else	list is	executed.

       while list [ do list ] done
	      A	 while	command	repeatedly executes the	while list and,	if its
	      value is zero, executes the do list; otherwise the  loop	termi-
	      nates.   The  value  returned  by	a while	command	is that	of the
	      last executed command in the do list.  Use  until	 in  place  of
	      while to negate the loop termination test.

       ( list )
	      Execute list in a	subshell.

       { 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	in esac	for while until	do done	{ }

       Command substitution
       The standard output from	a command enclosed in a	pair  of  back	quotes
       (``)  may  be used as part or all of a word; trailing new lines are re-

       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	] ...

	      A	parameter is a sequence	of letters, digits or  underscores  (a
	      name),  a	 digit,	 or  any of the	characters * @ # ? - $ !.  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.
	      If  parameter  is	a digit, it is a positional parameter.	If pa-
	      rameter is * or @	then all the positional	 parameters,  starting
	      with  $1,	 are  substituted separated by spaces.	$0 is set from
	      argument zero when the shell is invoked.

	      If parameter is set, substitute its value; otherwise  substitute

	      If parameter is not set, set it to word; the value of the	param-
	      eter is then substituted.	 Positional parameters may not be  as-
	      signed to	in this	way.

	      If parameter is set, substitute its value; otherwise, print word
	      and exit from the	shell.	If word	is omitted, a standard message
	      is printed.

	      If parameter is set, substitute word; otherwise substitute noth-

       In the above word is not	evaluated unless it is to be used as the  sub-
       stituted	string.	 (So that, for example,	echo ${d-`pwd`}	will only exe-
       cute pwd	if d is	unset.)

       The following parameters	are automatically set by the shell.

	      #	     The number	of positional parameters in decimal.
	      -	     Options supplied to the shell on invocation or by set.
	      ?	     The value returned	by the last executed command in	 deci-
	      $	     The process number	of this	shell.
	      !	     The  process  number  of  the last	background command in-

       The following parameters	are used but not set by	the shell.

	      HOME   The default argument (home	directory) for the cd command.
	      PATH   The search	path for commands (see execution).
	      MAIL   If	this variable is set to	the name of a mail  file,  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-

       Blank interpretation
       After  parameter	 and command substitution, any 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
       arguments (those	resulting from parameters that have no values) are re-

       File name generation
       Following substitution, each command word is scanned for	the characters
       *, ?  and [ .  If one of	these characters appears, 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, the	word is	left unchanged.	 The character .  at the start
       of  a file name or immediately following	a /, and the character /, must
       be matched explicitly.

       *      Matches any string, including the	null string.
       ?      Matches any single character.
       [ ... ]
	      Matches any one of the characters	enclosed.  A pair  of  charac-
	      ters  separated by - matches any character lexically between the

       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 by preceding	it with	a \.  \new-line	is ig-
       nored.  All characters enclosed between a pair of quote marks (''), ex-
       cept a single quote, are	quoted.	 Inside	double quotes () parameter and
       command substitution occurs and \ quotes	the characters \ ' " and $.

       "$*" is equivalent to "$1 $2 ..."  whereas
       "$@" is equivalent to "$1" "$2" ... .

       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 in-
       put is needed to	complete a command, the	secondary prompt ($PS2)	is is-

       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  be-
       fore 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, it is created; otherwise it is truncated to
	      zero length.

       >>word Use file word as standard	output.	 If the	file exists, output is
	      appended (by seeking to the end);	otherwise the file is created.

       <<word The shell	input is read up to a line the same as word, or	end of
	      file.   The  resulting  document becomes the standard input.  If
	      any character of word is quoted,	no  interpretation  is	placed
	      upon  the	 characters  of	the document; otherwise, parameter and
	      command substitution occurs, \new-line is	ignored, and \ is used
	      to quote the characters \	$ ' and	the first character of word.

	      The standard input is duplicated from file descriptor digit; see
	      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, the file descriptor created
       is that specified by the	digit (instead of the default 0	 or  1).   For

	    ...	2>&1

       creates file descriptor 2 to be a duplicate of file descriptor 1.

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

       The environment is a list of name-value pairs that is passed to an exe-
       cuted  program  in  the same way	as a normal argument list; see and The
       shell interacts with the	environment in several ways.   On  invocation,
       the  shell scans	the environment	and creates a parameter	for each valid
       name found (except IFS),	giving it the corresponding value.  (IFS  can-
       not  be set by the environment; it can only be set in the current shell
       session.)  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	composed 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 these two lines are

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

       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	prints
       'a=b c' and 'c':
       echo a=b	c
       set -k
       echo a=b	c

       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.  (But	see also trap.)

       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 with an

       The shell parameter $PATH defines the search  path  for	the  directory
       containing  the	command.  Each alternative directory name is separated
       by a colon (:).	The default path is :/bin:/usr/bin.   If  the  command
       name contains a /, the search path is not used.	Otherwise, each	direc-
       tory 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 subshell (that is,	a separate process) is
       spawned to read it.  A parenthesized command is also executed in	a sub-

       Special commands
       The following commands are executed in the shell	 process  and,	except
       where specified,	no input output	redirection is permitted for such com-

       :      No effect; the command does nothing.
       . file Read and execute commands	from file and return.  The search path
	      $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, break n levels.
	      [	 n  ] Resume the next iteration	of the enclosing for or	 while
	      loop.  If	n is specified,	resume at the nth enclosing loop.
       cd     [	 arg  ]	Change the current directory to	arg.  The shell	param-
	      eter $HOME is the	default	arg.
       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  arguments	may appear and if no other arguments are given
	      cause the	shell input output to be modified.
       exit   [	 n  ] Causes a noninteractive shell to exit with the exit sta-
	      tus specified by n.  If n	is omitted, the	exit status is that of
	      the last command executed.  (An end of file will also exit  from
	      the shell.)
       export [	 name ... ] The	given names are	marked for automatic export to
	      the environment of subsequently executed commands.  If no	 argu-
	      ments are	given, a list of exportable names is printed.
       login  [	 arg ... ] Equivalent to 'exec login arg ...'.
       read   name  ...	  One line is read from	the standard input; successive
	      words of the input are assigned to the variables name in	order,
	      with  leftover words to the last variable.  The return code is 0
	      unless the end-of-file is	encountered.
	      [	 name ... ] The	given names are	marked readonly	and the	values
	      of  these	names may not be changed by subsequent assignment.  If
	      no arguments are given, a	list of	all readonly names is printed.
       set    [	 -eknptuvx [  arg ... ]	]
	      -e If noninteractive, exit immediately if	a command fails.
	      -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.
	      -	 Turn off the -x and -v	options.

	      These  flags can also be used upon invocation of the shell.  The
	      current set of flags may be found	in $-.

	      Remaining	arguments are positional parameters and	are  assigned,
	      in  order,  to $1, $2, and so forth.  If no arguments are	given,
	      the values of all	names are printed.

       shift  The positional parameters	from $2...  are	renamed	$1...

       times  Print the	accumulated user and system times  for	processes  run
	      from the shell.

       trap   [	  arg  ] [  n  ] ...  The arg is a command to be read and exe-
	      cuted 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 executed in order of  signal  number.
	      If arg is	absent,	all trap(s) n are reset	to their original val-
	      ues.  If arg is the null string, this signal is ignored  by  the
	      shell  and  by  invoked commands.	 If n is 0, the	command	arg is
	      executed on exit from the	shell, otherwise upon receipt of  sig-
	      nal n as numbered	in The trap with no arguments prints a list of
	      commands associated with each signal number.

       umask [	nnn  ]
	      The user file creation mask is set to the	octal value nnn	.  For
	      further information, see If nnn is omitted, the current value of
	      the mask is printed.

       wait   Wait for all child background processes to terminate.   The  re-
	      turn code	from this command is that returned upon	termination of
	      the last process being waited for.

       If the first character of argument zero is -, commands  are  read  from
       $HOME/.profile,	if  such a file	exists.	 Commands are then read	as de-
       scribed below.  The following flags are interpreted by the  shell  when
       it is invoked.
       -c string  If the -c flag is present, commands are read from string.
       -s	  If  the  -s  flag is present or if no	arguments remain, then
		  commands are read from the standard input.  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 (as  told	by  gtty),  then  this
		  shell	 is  interactive.   In	this case the terminate	signal
		  SIGTERM is ignored (so that 'kill 0' does not	kill an	inter-
		  active  shell) and the interrupt signal SIGINT is caught and
		  ignored (so that wait	is interruptible).  For	further	infor-
		  mation, see In all cases SIGQUIT is ignored by the shell.

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

       If  << is used to provide standard input	to an asynchronous process in-
       voked by	&, the shell becomes confused about naming the input document.
       A garbage file is created, and the shell	complains about	not being able
       to find the file	by another name.

       The command is not 8-bit	clean. The command is 8-bit clean.

       VAX Only	Restriction
       If is run from another program (by the system  or  exec	system	calls)
       whose  maximum descriptor in use	is number 10, the prompt string	is not

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

See Also
       csh(1), sh5(1), test(1),	execve(2), environ(7)


Name | Syntax | Description | Restrictions | Diagnostics | Files | See Also

Want to link to this manual page? Use this URL:

home | help