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
RC(1)									 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
       offers  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
	      before 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
	      descriptors 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
	      before  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
       ignored 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
       sequence

	    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
       error 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
       intended	filename appearing in the command's argument list.

       In  order  to  place  the  output of a command at the end of an already
       existing	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,
       below), 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
       argument, 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
       another 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
       operation, 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
       bypassed.  For example, to append a single period at the	end of	$path,
       use:

	    echo $^path.

   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
       default,	$ifs has the value space-tab-newline.  The braces may be omit-
       ted  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
       default	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
	      invoked.	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
	      directory	 searching to begin in a directory other than the cur-
	      rent directory.

       history
	      $history contains	the name of  a	file  to  which	 commands  are
	      appended 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
	      default.	 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,
       unless  rc  has	been  invoked with the -d flag.	 However, user-defined
       signal 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
       behave 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
	      $cdpath is searched for possible locations of directory,	analo-
	      gous  to	the  searching of $path	for executable files.  With no
	      argument,	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
	      resulting	 string	 to rc for re-scanning.	 This is the only time
	      input 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.

       Bug reports should be mailed to <tjg@star.le.ac.uk>.

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://www.star.le.ac.uk/~tjg/rc/misc/td,  an  updated  version	of the
       above paper.

       history(1)

				  2003-07-17				 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+10.3-RELEASE+and+Ports>

home | help