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

FreeBSD Man Pages

Man Page or Keyword Search:
Man Architecture
Apropos Keyword Search (all sections) Output format
home | help
SH(1)									 SH(1)

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

SYNOPSIS
       sh [ -ceiknrstuvx ] [ arg ] ...

DESCRIPTION
       Sh is a command programming language that executes commands read	from a
       terminal	or a file.  See	invocation 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 200+status if it	termi-
       nates abnormally	(see signal(2) for a list of status values).

       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  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 &.	 ; 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  (non	 zero)	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 then in "$@"  is
	      assumed.	 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.

       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.   until  may  be  used  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	grave  accents
       (``)  may  be  used  as	part  or  all of a word; trailing newlines 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 ]	...

       ${parameter}
	      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	then it	is a positional	parameter.  If
	      parameter	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.

       ${parameter-word}
	      If parameter is set then substitute its value; otherwise substi-
	      tute word.

       ${parameter=word}
	      If  parameter  is	 not set then set it to	word; the value	of the
	      parameter	is then	substituted.  Positional parameters may	not be
	      assigned to in this way.

       ${parameter?word}
	      If  parameter is set then	substitute its value; otherwise, print
	      word and exit from the shell.  If	word is	omitted	then  a	 stan-
	      dard message is printed.

       ${parameter+word}
	      If  parameter  is	set then substitute word; otherwise substitute
	      nothing.

       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-
		     mal.
	      $	     The process number	of this	shell.
	      !	     The   process  number  of	the  last  background  command
		     invoked.

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

       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
       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 /, and the char-
       acter /,	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
	      pair.

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

	    ;	&   (	)   |	<   >	newline	  space	  tab

       A character may be quoted by  preceding	it  with  a  \.	  \newline  is
       ignored.	  All  characters enclosed between a pair of quote marks (''),
       except 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" ... .

       Prompting.
       When used interactively,	the shell prompts with the value of PS1	before
       reading a command.  If at any time a newline is typed and further input
       is needed to complete a command then the	 secondary  prompt  ($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	 trun-
	      cated to zero length.

       >>word Use  file	word as	standard output.  If the file exists then out-
	      put 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 then no interpretation is	placed
	      upon the characters of the document;  otherwise,	parameter  and
	      command  substitution occurs, \newline is	ignored, and \ is used
	      to quote the characters \	$ ` and	the first character of word.

       <&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 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 (/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.

       Environment.
       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  exec(2)
       and  environ(5).	  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.  Exe-
       cuted 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
       equivalent

	      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 the occur after the command name.  The following	prints
       `a=b c' and `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.  (But	see also trap.)

       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 an exec(2).

       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  / then the search path is not	used.  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 subshell (i.e., a separate  process)
       is  spawned  to read it.	 A parenthesized command is also executed in a
       subshell.

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

       :      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	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.
       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 non interactive 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 exit  from
	      the shell.)
       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 exportable names is printed.
       login [arg ...]
	      Equivalent to `exec login	arg ...'.
       newgrp [arg ...]
	      Equivalent to `exec newgrp 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.
       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 [-eknptuvx [arg ...]]
	      -e If non	interactive then 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, etc.	 If no arguments are  given  then  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] ...
	      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.  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
	      invoked commands.	 If n is 0 then	the command arg	is executed on
	      exit  from the shell, otherwise upon receipt of signal n as num-
	      bered in signal(2).  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 (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.	  The return code from this command is
	      that of the process waited for.

       Invocation.
       If the first character of argument zero is -, commands  are  read  from
       $HOME/.profile,	if  such  a  file  exists.   Commands are then read as
       described below.	 The following flags are interpreted by	the shell when
       it is invoked.
       -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
		  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
		  (see	signal(2))  is ignored (so that	`kill 0' does not kill
		  an interactive shell)	and the	 interrupt  signal  SIGINT  is
		  caught  and ignored (so that wait is interruptable).	In all
		  cases	SIGQUIT	is ignored by the shell.

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

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

SEE ALSO
       test(1),	exec(2),

DIAGNOSTICS
       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
       exit).

BUGS
       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 the file by another name.

									 SH(1)

NAME | SYNOPSIS | DESCRIPTION | FILES | SEE ALSO | DIAGNOSTICS | BUGS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=sh&manpath=Unix+Seventh+Edition>

home | help