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

FreeBSD Manual Pages

  
 
  

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

NAME
       rc - shell

SYNOPSIS
       rc [-deiIlnopsvx] [-c command] [arguments]

DESCRIPTION
       rc  is a	command	interpreter and	programming language similar to	sh(1).
       It is based on the AT&T Plan 9 shell of the same	name.  The  shell  of-
       fers  a	C-like	syntax (much more so than the C	shell),	and a powerful
       mechanism for manipulating variables.  It is reasonably small and  rea-
       sonably fast, especially	when compared to contemporary shells.  Its use
       is intended to be interactive, but the language lends  itself  well  to
       scripts.

OPTIONS
       -c     If  -c  is  present,  commands are executed from the immediately
	      following	argument.  Any further arguments to rc are  placed  in
	      $*.  Thus:

		   rc -c 'echo $*' 1 2 3

	      prints out

		   1 2 3

       -d     This  flag  causes rc not	to ignore SIGQUIT or SIGTERM.  Thus rc
	      can be made to dump core if sent SIGQUIT.	  This	flag  is  only
	      useful for debugging rc.

       -e     If  the -e flag is present, then rc will exit if the exit	status
	      of a command is false (nonzero).	rc will	not exit, however,  if
	      a	conditional fails, e.g., an if() command.

       -i     If the -i	flag is	present	or if the input	to rc is from a	termi-
	      nal (as determined by isatty(3)) then rc will be in  interactive
	      mode.   That  is,	a prompt (from $prompt(1)) will	be printed be-
	      fore an input line is taken, and rc will ignore SIGINT.

       -I     If the -I	flag is	present, or if the input to rc is not  from  a
	      terminal,	 then  rc will not be in interactive mode.  No prompts
	      will be printed, and SIGINT will cause rc	to exit.

       -l     If the -l	flag is	present, or if rc's argv[0][0] is a dash  (-),
	      then rc will behave as a login shell.  That is, it will run com-
	      mands from $home/.rcrc, if this file exists, before reading  any
	      other input.

       -n     This  flag  causes rc to read its	input and parse	it, but	not to
	      execute any commands.  This is useful  for  syntax  checking  on
	      scripts.	If used	in combination with the	-x flag, rc will print
	      each command as it is parsed in a	form similar to	the  one  used
	      for exporting functions into the environment.

       -o     This  flag  prevents  the	 usual	practice  of  trying  to  open
	      /dev/null	on file	descriptors 0, 1, and 2, if any	of  those  de-
	      scriptors	are inherited closed.

       -p     This flag	prevents rc from initializing shell functions from the
	      environment.  This allows	rc to run in a protected mode, whereby
	      it  becomes  more	 difficult for an rc script to be subverted by
	      placing false commands in	the environment.  (Note	that the pres-
	      ence of this flag	does not mean that it is safe to run setuid rc
	      scripts; the usual caveats about the setuid bit still apply.)

       -s     This flag	causes rc to read from standard	input.	Any  arguments
	      are placed in $*.

       -v     This flag	causes rc to echo its input to standard	error as it is
	      read.

       -x     This flag	causes rc to print every command on standard error be-
	      fore it is executed.  It can be useful for debugging rc scripts.

COMMANDS
       A  simple  command  is  a  sequence  of words, separated	by white space
       (space and tab) characters that ends with a newline, semicolon (;),  or
       ampersand  (&).	 The  first word of a command is the name of that com-
       mand.  If the name begins with /, ./, or	../, then the name is used  as
       an  absolute path name referring	to an executable file.	Otherwise, the
       name of the command is looked up	in a table of shell functions, builtin
       commands, or as a file in the directories named by $path.

   Background Tasks
       A  command  ending  with	& is run in the	background; that is, the shell
       returns immediately rather than waiting for the	command	 to  complete.
       Background  commands  have  /dev/null connected to their	standard input
       unless an explicit redirection for standard input is used.

   Subshells
       A command prefixed with an at-sign (@) is executed in a subshell.  This
       insulates  the  parent  shell from the effects of state changing	opera-
       tions such as a cd or a variable	assignment.  For example:

	    @ {cd ..; make}

       will run	make(1)	in the parent directory	(..),  but  leaves  the	 shell
       running in the current directory.

   Line	continuation
       A  long	logical	 line  may be continued	over several physical lines by
       terminating each	line (except the last)	with  a	 backslash  (\).   The
       backslash-newline  sequence  is treated as a space.  A backslash	is not
       otherwise special to rc.	 (In addition, inside quotes a backslash loses
       its special meaning even	when it	is followed by a newline.)

   Quoting
       rc interprets several characters	specially; special characters automat-
       ically terminate	words.	The following characters are special:

	    # ;	& | ^ $	= ` ' {	} ( ) <	>

       The single quote	(') prevents special treatment of any character	 other
       than  itself.   All characters, including control characters, newlines,
       and backslashes between two quote characters are	treated	as an uninter-
       preted  string.	 A quote character itself may be quoted	by placing two
       quotes in a row.	 The minimal sequence needed to	enter the quote	 char-
       acter is	''''.  The empty string	is represented by ''.  Thus:

	    echo 'What''s the plan, Stan?'

       prints out

	    What's the plan, Stan?

       The  number  sign (#) begins a comment in rc.  All characters up	to but
       not including the next newline are ignored.  Note that  backslash  con-
       tinuation  does	not  work inside a comment, i.e., the backslash	is ig-
       nored along with	everything else.

   Grouping
       Zero or more commands may be grouped within braces (``{''  and  ``}''),
       and  are	 then  treated as one command.	Braces do not otherwise	define
       scope; they are used only for command grouping.	In particular, be wary
       of the command:

	    for	(i) {
		command
	    } |	command

       Since  pipe  binds tighter than for, this command does not perform what
       the user	expects	it to.	Instead, enclose the whole  for	 statement  in
       braces:

	    {for (i) command} |	command

       Fortunately,  rc's grammar is simple enough that	a (confident) user can
       understand it by	examining the skeletal yacc(1) grammar at the  end  of
       this man	page (see the section entitled GRAMMAR).

   Input and output
       The standard output may be redirected to	a file with

	    command > file

       and the standard	input may be taken from	a file with

	    command < file

       Redirections  can  appear  anywhere in the line:	the word following the
       redirection symbol is the filename and must be quoted  if  it  contains
       spaces or other special characters.  These are all equivalent.

	    echo 1 2 3 > foo
	    > foo echo 1 2 3
	    echo 1 2 > foo 3

       File  descriptors  other	than 0 and 1 may be specified also.  For exam-
       ple, to redirect	standard error to a file, use:

	    command >[2] file

       In order	to duplicate a file descriptor,	use >[n=m].  Thus to  redirect
       both standard output and	standard error to the same file, use

	    command > file >[2=1]

       As in sh, redirections are processed from left to right.	 Thus this se-
       quence

	    command >[2=1] > file

       is usually a mistake.  It first duplicates standard error  to  standard
       output;	then redirects standard	output to a file, leaving standard er-
       ror wherever standard output originally was.

       To close	a file descriptor that may be open, use	>[n=].	 For  example,
       to close	file descriptor	7:

	    command >[7=]

       Note that no spaces may appear in these constructs:

	    command > [2] file

       would  send the output of the command to	a file named [2], with the in-
       tended filename appearing in the	command's argument list.

       In order	to place the output of a command at the	end of an already  ex-
       isting file, use:

	    command >> file

       If the file does	not exist, then	it is created.

       ``Here documents'' are supported	as in sh with the use of

	    command << 'eof-marker'

       Subsequent  lines  form	the standard input of the command, till	a line
       containing just the marker, in this case	eof-marker, is encountered.

       If the end-of-file marker is enclosed in	quotes,	then no	variable  sub-
       stitution  occurs  inside the here document.  Otherwise,	every variable
       is substituted by its space-separated-list value	(see Flat  Lists,  be-
       low),  and  if  a  ^  character follows a variable name,	it is deleted.
       This allows the unambiguous use of variables adjacent to	text, as in

	    $variable^follow

       To include a literal $ in a here	document when an unquoted  end-of-file
       marker is being used, enter it as $$.

       Additionally,  rc  supports ``here strings'', which are like here docu-
       ments, except that input	is taken directly from a string	on the command
       line.  Their use	is illustrated here:

	    cat	<<< 'this is a here string' | wc

       (This  feature enables rc to export functions using here	documents into
       the environment;	the author does	not expect users to find this  feature
       useful.)

   Pipes
       Two  or more commands may be combined in	a pipeline by placing the ver-
       tical bar (|) between them.  The	standard output	(file descriptor 1) of
       the  command on the left	is tied	to the standard	input (file descriptor
       0) of the command on the	right.	The  notation  |[n=m]  indicates  that
       file descriptor n of the	left process is	connected to file descriptor m
       of the right process.  |[n] is a	shorthand for |[n=0].  As an  example,
       to pipe the standard error of a command to wc(1), use:

	    command |[2] wc

       As  with	file redirections, no spaces may occur in the construct	speci-
       fying numbered file descriptors.

       The exit	status of a pipeline is	considered true	if and only  if	 every
       command in the pipeline exits true.

   Commands as Arguments
       Some commands, like cmp(1) or diff(1), take their arguments on the com-
       mand line, and do not read input	from standard input.  It is convenient
       sometimes  to  build nonlinear pipelines	so that	a command like cmp can
       read the	output of two other commands at	once.  rc does it like this:

	    cmp	<{command} <{command}

       compares	the output of the two commands in braces.   Note:  since  this
       form  of	 redirection  is implemented with some kind of pipe, and since
       one cannot lseek(2) on a	pipe, commands that use	 lseek(2)  will	 hang.
       For example, some versions of diff(1) use lseek(2) on their inputs.

       Data  can  be sent down a pipe to several commands using	tee(1) and the
       output version of this notation:

	    echo hi there | tee	>{sed 's/^/p1 /'} >{sed	's/^/p2	/'}

CONTROL	STRUCTURES
       The following may be used for control flow in rc:

   If-Else Statements
       if (test) {
	   cmd
       } else cmd
	      The test is executed, and	if its	return	status	is  zero,  the
	      first  command is	executed, otherwise the	second is.  Braces are
	      not mandatory around the commands.  However, an  else  statement
	      is  valid	 only  if  it  follows a close-brace on	the same line.
	      Otherwise, the if	is taken to be a simple-if:

		   if (test)
		       command

   While and For Loops
       while (test) cmd
	      rc executes the test and performs	the command  as	 long  as  the
	      test is true.

       for (var	in list) cmd
	      rc sets var to each element of list (which may contain variables
	      and backquote substitutions) and runs cmd.  If  ``in  list''  is
	      omitted,	then rc	will set var to	each element of	$*.  For exam-
	      ple:

		   for (i in `{ls -F | grep '\*$' | sed	's/\*$//'}) { commands }

	      will set $i to the name of each file in  the  current  directory
	      that is executable.

   Switch
       switch (list) { case ...	}
	      rc  looks	inside the braces after	a switch for statements	begin-
	      ning with	the word case.	If any of the patterns following  case
	      match  the  list	supplied to switch, then the commands up until
	      the next case statement are executed.  The metacharacters	 *,  [
	      or  ?   should not be quoted; matching is	performed only against
	      the strings in list, not against file names.  (Matching for case
	      statements is the	same as	for the	~ command.)

   Logical Operators
       There  are  a number of operators in rc which depend on the exit	status
       of a command.

	    command && command

       executes	the first command and then executes the	second command if  and
       only  if	 the  first command exits with a zero exit status (``true'' in
       Unix).

	    command || command

       executes	the first command and then executes the	second command if  and
       only  if	 the first command exits with a	nonzero	exit status (``false''
       in Unix).

	    ! command

       negates the exit	status of a command.

PATTERN	MATCHING
       There are two forms of pattern matching	in  rc.	  One  is  traditional
       shell  globbing.	  This	occurs	in matching for	file names in argument
       lists:

	    command argument argument ...

       When the	characters *, [	or ?  occur in	an  argument  or  command,  rc
       looks  at  the argument as a pattern for	matching against files.	 (Con-
       trary to	the behavior other shells exhibit, rc will only	 perform  pat-
       tern  matching  if a metacharacter occurs unquoted and literally	in the
       input.  Thus,

	    foo='*'
	    echo $foo

       will always echo	just a star.  In order for non-literal	metacharacters
       to  be  expanded, an eval statement must	be used	in order to rescan the
       input.)	Pattern	matching occurs	according to the following rules: a  *
       matches	any  number  (including	zero) of characters.  A	?  matches any
       single character, and a [ followed by a number of  characters  followed
       by a ] matches a	single character in that class.	 The rules for charac-
       ter class matching are the same as those	for ed(1), with	the  exception
       that  character	class negation is achieved with	the tilde (~), not the
       caret (^), since	the caret already means	something else in rc.

       rc also matches patterns	against	strings	with the ~ command:

	    ~ subject pattern pattern ...

       ~ sets $status to zero if and only if a supplied	 pattern  matches  any
       single element of the subject list.  Thus

	    ~ foo f*

       sets status to zero, while

	    ~ (bar baz)	f*

       sets status to one.  The	null list is matched by	the null list, so

	    ~ $foo ()

       checks  to see whether $foo is empty or not.  This may also be achieved
       by the test

	    ~ $#foo 0

       Note that inside	a ~ command rc does not	match  patterns	 against  file
       names, so it is not necessary to	quote the characters *,	[ and ?.  How-
       ever, rc	does expand the	 subject  against  filenames  if  it  contains
       metacharacters.	Thus, the command

	    ~ *	?

       returns	true  if any of	the files in the current directory have	a sin-
       gle-character name.  If the ~ command is	given a	list as	its first  ar-
       gument,	then  a	 successful  match against any of the elements of that
       list will cause ~ to return true.  For example:

	    ~ (foo goo zoo) z*

       is true.

LISTS AND VARIABLES
       The primary data	structure in rc	is the list, which is  a  sequence  of
       words.	Parentheses are	used to	group lists.  The empty	list is	repre-
       sented by ().  Lists have no hierarchical structure; a list inside  an-
       other  list  is expanded	so the outer list contains all the elements of
       the inner list.	Thus, the following are	all equivalent

	    one	two three

	    (one two three)

	    ((one) () ((two three)))

       Note that the null string, '', and the null list, (), are two very dif-
       ferent  things.	Assigning the null string to a variable	is a valid op-
       eration,	but it does not	remove its definition.

	    null = '' empty = () echo $#null $#empty

       produces	the output

	    1 0

   List	Concatenation
       Two lists may be	joined by the concatenation operator (^).   Concatena-
       tion  works according to	the following rules: if	the two	lists have the
       same number of elements,	then concatenation is pairwise:

	    echo (a- b-	c-)^(1 2 3)

       produces	the output

	    a-1	b-2 c-3

       Otherwise, at least one of the lists must have a	 single	 element,  and
       then the	concatenation is distributive:

	    cc -^(O g c) (malloc alloca)^.c

       has the effect of performing the	command

	    cc -O -g -c	malloc.c alloca.c

       A single	word is	a list of length one, so

	    echo foo^bar

       produces	the output

	    foobar

   Free	Carets
       rc  inserts carets (concatenation operators) for	free in	certain	situa-
       tions, in order to save some typing on the user's behalf.  For example,
       the above example could also be typed in	as:

	    opts=(O g c) files=(malloc alloca) cc -$opts $files.c

       rc  takes  care	to insert a free-caret between the ``-'' and $opts, as
       well as between $files and .c.  The rule	for free carets	is as follows:
       if  a word or keyword is	immediately followed by	another	word, keyword,
       dollar-sign or backquote, then rc inserts a caret between them.

   Variables
       A list may be assigned to a variable, using the notation:

	    var	= list

       The special variable * may also be assigned to using this notation;  rc
       has no set builtin.

       Any  non-empty sequence of characters, except a sequence	including only
       digits, may be used as a	variable name.	Any character except = may  be
       used,  but  special  characters must be quoted.	All user-defined vari-
       ables are exported into the environment.

       The value of a variable is referenced with the dollar ($) operator:

	    $var

       Any variable which has not been assigned	a value	returns	the null list,
       (), when	referenced.  Multiple references are allowed:

	    a =	foo
	    b =	a
	    echo $ $ b

       prints

	    foo

       A  variable's definition	may also be removed by assigning the null list
       to a variable:

	    var=()

       For ``free careting'' to	work correctly,	rc must	make  certain  assump-
       tions  about what characters may	appear in a variable name.  rc assumes
       that a variable name consists only of alphanumeric  characters,	under-
       score  (_) and star (*).	 To reference a	variable with other characters
       in its name, quote the variable name.  Thus:

	    echo $'we$Ird:Variab!le'

   Local Variables
       Any number of variable assignments may be made local to a  single  com-
       mand by typing:

	    a=foo b=bar	... command

       The command may be a compound command, so for example:

	    path=. ifs=() {
		...
	    }

       sets  path  to .	 and removes ifs for the duration of one long compound
       command.

   Variable Subscripts
       Variables may be	subscripted with the notation

	    $var(n)

       where n is a list of integers (origin 1).  The opening parenthesis must
       immediately  follow the variable	name.  The list	of subscripts need not
       be in order or even unique.  Thus,

	    a=(one two three)
	    echo $a(3 3	3)

       prints

	    three three	three

       If n references a nonexistent element, then $var(n)  returns  the  null
       list.   The  notation  $n,  where  n  is	an integer, is a shorthand for
       $*(n).  Thus, rc's arguments may	be referred to as $1, $2, and so on.

       Note also that the list of subscripts may be given by any of rc's  list
       operations:

	    $var(`{awk 'BEGIN{for(i=1;i<=10;i++)print i;exit; }'})

       returns the first 10 elements of	$var.

       To count	the number of elements in a variable, use

	    $#var

       This  returns  a	 single-element	 list,	with the number	of elements in
       $var.

   Flat	Lists
       In order	to create a single-element list	 from  a  multi-element	 list,
       with  the  components space-separated, use the dollar-caret ($^)	opera-
       tor:

	    $^var

       This is useful when the normal list concatenation rules need to be  by-
       passed.	 For  example,	to append a single period at the end of	$path,
       use:

	    echo $^path.

       For compability with the	Plan 9 rc,

	    $"var

       is accepted as a	synonym	for dollar-caret.

   Backquote Substitution
       A list may be formed from the output of a command  by  using  backquote
       substitution:

	    `{ command }

       returns	a  list	 formed	 from  the  standard  output of	the command in
       braces.	$ifs is	used to	split the output into list elements.   By  de-
       fault, $ifs has the value space-tab-newline.  The braces	may be omitted
       if the command is a single word.	 Thus  `ls  may	 be  used  instead  of
       `{ls}.  This last feature is useful when	defining functions that	expand
       to useful argument lists.  A frequent use is:

	    fn src { echo *.[chy] }

       followed	by

	    wc `src

       (This will print	out a word-count of all	C source files in the  current
       directory.)

       In order	to override the	value of $ifs for a single backquote substitu-
       tion, use:

	    `` (ifs-list) { command }

       $ifs will be temporarily	ignored	and the	command's output will be split
       as specified by the list	following the double backquote.	 For example:

	    `` ($nl :) {cat /etc/passwd}

       splits up /etc/passwd into fields, assuming that	$nl contains a newline
       as its value.

SPECIAL	VARIABLES
       Several variables are known to rc and are treated  specially.   In  the
       following  list,	``default'' indicates that rc gives the	variable a de-
       fault value on startup; ``no-export'' indicates that  the  variable  is
       never  exported;	and ``read-only'' indicates that an attempt to set the
       variable	will silently have no effect.

       Also, ``alias'' means that the variable is aliased to the same name  in
       capitals.   For	example,  an assignment	to $cdpath causes an automatic
       assignment to $CDPATH, and vice-versa.  If $CDPATH is set  when	rc  is
       started,	 its value is imported into $cdpath.  $cdpath and $path	are rc
       lists; $CDPATH and $PATH	are colon-separated  lists.   Only  the	 names
       spelt in	capitals are exported into the environment.

       * (no-export)
	      The  argument  list  of rc.  $1, $2, etc.	are the	same as	$*(1),
	      $*(2), etc.

       0 (default no-export)
	      The variable $0 holds the	value of argv[0] with which rc was in-
	      voked.   Additionally,  $0  is set to the	name of	a function for
	      the duration of the execution of that function, and $0  is  also
	      set  to  the name	of the file being interpreted for the duration
	      of a .  command.	$0 is not an  element  of  $*,	and  is	 never
	      treated as one.

       apid (no-export)
	      The process ID of	the last process started in the	background.

       apids (no-export	read-only)
	      A	list whose elements are	the process IDs	of all background pro-
	      cesses which are still alive, or which have died	and  have  not
	      been waited for yet.

       bqstatus	(no-export)
	      The  exit	 status	 of  the  rc forked to execute the most	recent
	      backquote	substitution.  Note that, unlike $status, $bqstatus is
	      always a single element list (see	EXIT STATUS below).  For exam-
	      ple:

		   echo	foo |grep bar; whatis status

	      prints

		   status=(0 1)

	      whereas

		   x=`{echo foo	|grep bar}; whatis bqstatus

	      prints

		   bqstatus=1

       cdpath (alias)
	      A	list of	directories to search for the target of	a cd  command.
	      The empty	string stands for the current directory.  Note that if
	      the $cdpath variable does	not  contain  the  current  directory,
	      then the current directory will not be searched; this allows di-
	      rectory searching	to begin in a directory	other than the current
	      directory.

       history
	      $history	contains  the name of a	file to	which commands are ap-
	      pended as	rc reads them.	This facilitates the use of  a	stand-
	      alone history program (such as history(1)) which parses the con-
	      tents of the history file	and presents them to rc	 for  reinter-
	      pretation.  If $history is not set, then rc does not append com-
	      mands to any file.

       home (alias)
	      The default directory for	the builtin cd command,	and the	direc-
	      tory  in	which rc looks to find its initialization file,	.rcrc,
	      if rc has	been started up	as a login shell.

       ifs (default)
	      The internal field separator, used for splitting up  the	output
	      of  backquote  commands for digestion as a list.	On startup, rc
	      assigns the list containing the characters space,	tab, and  new-
	      line to $ifs.

       path (alias)
	      This  is	a  list	of directories to search in for	commands.  The
	      empty string stands for the current directory.  If neither $PATH
	      nor  $path is set	at startup time, $path assumes a default value
	      suitable for your	system.	  This	is  typically  (/usr/local/bin
	      /usr/bin /usr/ucb	/bin .)

       pid (default no-export)
	      On startup, $pid is initialized to the numeric process ID	of the
	      currently	running	rc.

       prompt (default)
	      This variable holds the two prompts (in list  form,  of  course)
	      that  rc	prints.	  $prompt(1) is	printed	before each command is
	      read, and	$prompt(2) is printed when input is expected  to  con-
	      tinue  on	 the  next  line.  rc sets $prompt to ('; ' '')	by de-
	      fault.  The reason for this is that it enables  an  rc  user  to
	      grab  commands from previous lines using a mouse,	and to present
	      them to rc for re-interpretation;	the semicolon prompt is	simply
	      ignored  by rc.  The null	$prompt(2) also	has its	justification:
	      an  rc  script,  when  typed  interactively,  will   not	 leave
	      $prompt(2)'s  on	the  screen, and can therefore be grabbed by a
	      mouse and	placed directly	into a file for	use as a shell script,
	      without further editing being necessary.

       prompt (function)
	      If this function is defined, then	it gets	executed every time rc
	      is about to print	$prompt(1).

       status (no-export read-only)
	      The exit status of the last command.  If the command exited with
	      a	numeric	value, that number is the status.  If the command died
	      with a signal, the status	is the name of that signal; if a  core
	      file  was	 created, the string ``+core'' is appended.  The value
	      of $status for a pipeline	is a list, with	one entry,  as	above,
	      for each process in the pipeline.	 For example, the command

		   ls |	wc

	      usually sets $status to (0 0).

       version (default)
	      On  startup, the first element of	this list variable is initial-
	      ized to a	string which identifies	this version of	rc.  The  sec-
	      ond  element  is	initialized  to	a string which can be found by
	      ident(1) and the what command of sccs(1).

FUNCTIONS
       rc functions are	identical to rc	scripts, except	that they  are	stored
       in memory and are automatically exported	into the environment.  A shell
       function	is declared as:

	    fn name { commands }

       rc scans	the definition until the close-brace, so the function can span
       more than one line.  The	function definition may	be removed by typing

	    fn name

       (One  or	more names may be specified.  With an accompanying definition,
       all names receive the same definition.  This is	sometimes  useful  for
       assigning  the  same signal handler to many signals.  Without a defini-
       tion, all named functions are deleted.)	When a function	 is  executed,
       $*  is  set  to	the arguments to that function for the duration	of the
       command.	 Thus a	reasonable definition for l, a	shorthand  for	ls(1),
       could be:

	    fn l { ls -FC $* }

       but not

	    fn l { ls -FC } # WRONG

INTERRUPTS AND SIGNALS
       rc  recognizes a	number of signals, and allows the user to define shell
       functions which act as signal handlers.	rc  by	default	 traps	SIGINT
       when  it	 is in interactive mode.  SIGQUIT and SIGTERM are ignored, un-
       less rc has been	invoked	with the -d flag.  However, user-defined  sig-
       nal  handlers  may be written for these and all other signals.  The way
       to define a signal handler is to	write a	function by the	 name  of  the
       signal in lower case.  Thus:

	    fn sighup {	echo hangup; rm	/tmp/rc$pid.*; exit }

       In  addition  to	 Unix  signals,	 rc  recognizes	 the artificial	signal
       SIGEXIT which occurs as rc is about to exit.

       In order	to remove a signal handler's definition, remove	it  as	though
       it were a regular function.  For	example:

	    fn sigint

       returns the handler of SIGINT to	the default value.  In order to	ignore
       a signal, set the signal	handler's value	to {}.	Thus:

	    fn sigint {}

       causes SIGINT to	be ignored by the shell.  Only signals that are	 being
       ignored	are  passed on to programs run by rc; signal functions are not
       exported.

       On System V-based Unix systems, rc will not allow you to	trap SIGCLD.

BUILTIN	COMMANDS
       Builtin commands	execute	in the context of the shell, but otherwise be-
       have exactly like other commands.  Although !, ~	and @ are not strictly
       speaking	builtin	commands, they can usually be used as such.

       . [-i] file [arg	...]
	      Reads file as input to rc	and executes its contents.  With a  -i
	      flag, input is interactive.  Thus	from within a shell script,

		   . -i	/dev/tty

	      does the ``right thing''.

       break  Breaks from the innermost	for or while, as in C.	It is an error
	      to invoke	break outside of a loop.  (Note	that there is no break
	      keyword between commands in switch statements, unlike C.)

       builtin command [arg ...]
	      Executes	the  command  ignoring	any function definition	of the
	      same name.  This command is present to allow functions with  the
	      same  names as builtins to use the underlying builtin or binary.
	      For example:

		   fn ls { builtin ls -FC $* }

	      is a reasonable way to pass a default set	of arguments to	ls(1),
	      whereas

		   fn ls { ls -FC $* } # WRONG

	      is  a  non-terminating recursion,	which will cause rc to exhaust
	      its stack	space and (eventually) terminate if it is executed.

       cd [directory]
	      Changes the current directory to directory.  The	variable  $cd-
	      path  is searched	for possible locations of directory, analogous
	      to the searching of $path	for executable files.  With  no	 argu-
	      ment, cd changes the current directory to	$home.

       echo [-n] [--] [arg ...]
	      Prints  its  arguments  to standard output, terminated by	a new-
	      line.  Arguments are separated by	spaces.	 If the	first argument
	      is -n no final newline is	printed.  If the first argument	is --,
	      then all other arguments are echoed literally.  This is used for
	      echoing a	literal	-n.

       eval [list]
	      Concatenates  the	elements of list with spaces and feeds the re-
	      sulting string to	rc for re-scanning.  This is the only time in-
	      put is rescanned in rc.

       exec [arg ...]
	      Replaces	rc  with the given command.  If	the exec contains only
	      redirections, then these redirections apply to the current shell
	      and the shell does not exit.  For	example,

		   exec	>[2] err.out

	      places further output to standard	error in the file err.out.

       exit [status]
	      Cause  the current shell to exit with the	given exit status.  If
	      no argument is given, the	current	value of $status is used.

       limit [-h] [resource [value]]
	      Similar to the csh(1) limit builtin, this	command	operates  upon
	      the  BSD-style  resource	limits of a process.  The -h flag dis-
	      plays/alters the hard limits.  The resources which can be	 shown
	      or altered are cputime, filesize,	datasize, stacksize, coredump-
	      size, memoryuse, and, where supported,  descriptors,  memoryuse,
	      memoryrss, maxproc, memorylocked,	and filelocks.	For example:

		   limit coredumpsize 0

	      disables	core  dumps.   To  set	a soft limit equal to the hard
	      limit:

		   limit `{limit -h datasize}

       newpgrp
	      Puts rc into a new process group.	 This builtin  is  useful  for
	      making  rc behave	like a job-control shell in a hostile environ-
	      ment.  One example is the	NeXT Terminal program,	which  implic-
	      itly assumes that	each shell it forks will put itself into a new
	      process group.

       return [n]
	      Returns from the current function, with status n,	where n	 is  a
	      valid exit status, or a list of them.  Thus it is	legal to have

		   return (sigpipe 1 2 3)

	      (This  is	 commonly  used	to allow a function to return with the
	      exit status of a previously executed pipeline of commands.)   If
	      n	is omitted, then $status is left unchanged.  It	is an error to
	      invoke return when not inside a function.

       shift [n]
	      Deletes n	elements from the beginning of $* and shifts the other
	      elements down by n.  n defaults to 1.

       umask [mask]
	      Sets  the	current	umask (see umask(2)) to	the octal mask.	 If no
	      argument is present, the current mask value is printed.

       wait [pid]
	      Waits for	process	with the specified pid,	which must  have  been
	      started  by  rc,	to exit.  If no	pid is specified, rc waits for
	      all its child processes to exit.

       whatis [-b] [-f]	[-p] [-s] [-v] [--] [name ...]
	      Prints a definition of the named objects.	 For builtins, builtin
	      foo  is printed; for functions, including	signal handlers, their
	      definitions are printed; for executable files,  path  names  are
	      printed; and for variables, their	values are printed.  The flags
	      restrict output to  builtins,  functions,	 executable  programs,
	      signal  handlers,	 and variables,	respectively.  If no names are
	      specified, rc lists all objects of that type.  (This is not per-
	      mitted  for  -p.)	  Without  arguments,  whatis is equivalent to
	      whatis -fv, and prints the values	of  all	 shell	variables  and
	      functions.

	      Note  that  whatis output	is suitable for	input to rc; by	saving
	      the output of whatis in a	file, it should	be possible to	recre-
	      ate  the	state  of  rc by sourcing this file with a .  command.
	      Another note: whatis -s >	file cannot be used to store the state
	      of  rc's	signal handlers	in a file, because builtins with redi-
	      rections are run in a subshell, and rc  always  restores	signal
	      handlers to their	default	value after a fork().

	      Since  whatis uses getopt(3) to parse its	arguments, you can use
	      the special argument -- to terminate its flags.  This allows you
	      to  use names beginning with a dash, such	as the history(1) com-
	      mands.  For example,

		   whatis -- -p

EXAMPLES
       The shift builtin only shifts $*.  This function	can shift any variable
       (except $lshift).

	    fn lshift {	lshift=$*; *=$$1; shift	$lshift(2); $lshift(1)=$* }

       With this definition in place,

	    walrus = (shoes ships sealing-wax cabbages kings)
	    lshift walrus 3
	    whatis walrus

       prints

	    walrus=(cabbages kings)

       The  $^var  operator  flattens a	list by	separating each	element	with a
       space.  This function allows the	separator to be	an arbitrary string.

	    fn lflat {
	      lflat=$*;	*=$$1
	      while () {
		echo -n	$1; shift
		~ $#* 0	&& break
		echo -n	$lflat(2)
	    }

       With this definition in place,

	    hops=(uunet	mcvax ukc tlg)
	    lflat hops !

       prints (with no final newline)

	    uunet!mcvax!ukc!tlg

EXIT STATUS
       The exit	status of rc is	normally the same as that of the last  command
       executed.  If the last command was a pipeline, rc exits 0 if every com-
       mand in the pipeline did; otherwise it exits 1.

       rc can be made to exit with a particular	status using the exit builtin.

GRAMMAR
       Here is rc's grammar, edited to remove semantic actions.

	    %term ANDAND BACKBACK BANG CASE COUNT DUP ELSE END FLAT FN FOR IF IN
	    %term OROR PIPE REDIR SUB SUBSHELL SWITCH TWIDDLE WHILE WORD HUH

	    %left WHILE	')' ELSE
	    %left ANDAND OROR '\n'
	    %left BANG SUBSHELL
	    %left PIPE
	    %right '$'
	    %left SUB

	    %start rc

	    %%

	    rc:	line end
		 | error end

	    end: END /*	EOF */ | '\n'

	    cmdsa: cmd ';' | cmd '&'

	    line: cmd |	cmdsa line

	    body: cmd |	cmdsan body

	    cmdsan: cmdsa | cmd	'\n'

	    brace: '{' body '}'

	    paren: '(' body ')'

	    assign: first '=' word

	    epilog: /* empty */	| redir	epilog

	    redir: DUP | REDIR word

	    case: CASE words ';' | CASE	words '\n'

	    cbody: cmd | case cbody | cmdsan cbody

	    iftail: cmd	   %prec ELSE
		 | brace ELSE optnl cmd

	    cmd	 : /* empty */	%prec WHILE
		 | simple
		 | brace epilog
		 | IF paren optnl iftail
		 | FOR '(' word	IN words ')' optnl cmd
		 | FOR '(' word	')' optnl cmd
		 | WHILE paren optnl cmd
		 | SWITCH '(' word ')' optnl '{' cbody '}'
		 | TWIDDLE optcaret word words
		 | cmd ANDAND optnl cmd
		 | cmd OROR optnl cmd
		 | cmd PIPE optnl cmd
		 | redir cmd	%prec BANG
		 | assign cmd	%prec BANG
		 | BANG	optcaret cmd
		 | SUBSHELL optcaret cmd
		 | FN words brace
		 | FN words

	    optcaret: /* empty */ | '^'

	    simple: first | simple word	| simple redir

	    first: comword | first '^' sword

	    sword: comword | keyword

	    word: sword	| word '^' sword

	    comword: '$' sword
		 | '$' sword SUB words ')'
		 | COUNT sword
		 | FLAT	sword
		 | '`' sword
		 | '`' brace
		 | BACKBACK word     brace | BACKBACK word sword
		 | '(' words ')'
		 | REDIR brace
		 | WORD

	    keyword: FOR | IN |	WHILE |	IF | SWITCH
		 | FN |	ELSE | CASE | TWIDDLE |	BANG | SUBSHELL

	    words: /* empty */ | words word

	    optnl: /* empty */ | optnl '\n'

FILES
       $HOME/.rcrc, /tmp/rc*, /dev/null

CREDITS
       rc was written by Byron Rakitzis, with valuable help from  Paul	Haahr,
       Hugh  Redelmeier	 and  David  Sanderson.	  The design of	this shell was
       copied from the rc that Tom Duff	wrote at Bell Labs.

BUGS
       There is	a compile-time limit on	the number of ;	separated commands  in
       a  line:	 usually  500.	 This is sometimes a problem for automatically
       generated scripts: substituting the newline character for ; avoids  the
       limit.

       On  modern  systems that	support	/dev/fd	or /proc/self/fd, <{foo} style
       redirection is implemented that way.  However, on older systems	it  is
       implemented  with  named	pipes.	Allegedly, it is sometimes possible to
       foil rc into removing the FIFO it places	in /tmp	prematurely, or	it  is
       even  possible  to cause	rc to hang.  (The current maintainer has never
       seen this, but then he doesn't use systems which	lack /dev/fd any more.
       If anybody can reproduce	this problem, please let the maintainer	know.)

       The  echo command does not need to be a builtin.	 It is one for reasons
       of performance and portability (of rc scripts).

       There should be a way to	avoid exporting	a variable.

       Extra parentheses around	a ~ expression or a !  expression are a	syntax
       error.  Thus, this code is illegal.

	    while ((~ $1 -*) &&	(! ~ $1	--)) { ...

       The redundant inner parentheses must be omitted.

       Variable	subscripting cannot be used in here documents.

       The limit builtin silently ignores extra	arguments.

       Backquote substitution never produces empty strings - multiple consecu-
       tive occurrences	of the separator are treated the same as a single  oc-
       currence.

	    ifs=! { x =	`{echo -n a!!b}; whatis	x }
	    x=(a b) # NOT x=(a '' b)

       Bug reports should be mailed to
       <toby@paccrat.org>.

INCOMPATIBILITIES
       Here  is	 a  list  of features which distinguish	this incarnation of rc
       from the	one described in the Bell Labs manual pages:

       The Tenth Edition rc does not have the else keyword.   Instead,	if  is
       optionally  followed  by	an if not clause which is executed if the pre-
       ceding if test does not succeed.

       Backquotes are slightly different in Tenth Edition rc: a	backquote must
       always  be  followed  by	a left-brace.  This restriction	is not present
       for single-word commands	in this	rc.

       For .  file, the	Tenth Edition rc searches $path	 for  file.   This  rc
       does not, since it is not considered useful.

       The  list  flattening operator, $^foo, is spelt $"foo in	those versions
       of the Bell Labs	rc which have it.

       The following are all new with this version of rc: The  -n  flag,  here
       strings	(they  facilitate  exporting  of functions with	here documents
       into the	environment), the return and break keywords, the echo builtin,
       the bqstatus and	version	variables, the support for the GNU readline(3)
       library,	and the	support	for the	prompt function.  This rc also sets $0
       to the name of a	function being executed/file being sourced.

SEE ALSO
       ``rc  --	 A  Shell for Plan 9 and UNIX Systems'', Unix Research System,
       Tenth Edition, Volume 2.	(Saunders College Publishing)

       http://static.tobold.org/rc/rc-duff.html, an  updated  version  of  the
       above paper.

       history(1)

				  2015-05-13				 RC(1)

NAME | SYNOPSIS | DESCRIPTION | OPTIONS | COMMANDS | CONTROL STRUCTURES | PATTERN MATCHING | LISTS AND VARIABLES | SPECIAL VARIABLES | FUNCTIONS | INTERRUPTS AND SIGNALS | BUILTIN COMMANDS | EXAMPLES | EXIT STATUS | GRAMMAR | FILES | CREDITS | BUGS | INCOMPATIBILITIES | SEE ALSO

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=rc&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help