Man Linux: Main Page and Category List

NAME

       set - set or unset options and positional parameters

SYNOPSIS

       set [-abCefmnuvx][-h][-o option][argument...]

       set [+abCefmnuvx][+h][+o option][argument...]

       set -- [argument...]

       set -o

       set +o

DESCRIPTION

       If no options or arguments are specified, set shall write the names and
       values of all shell variables in the collation sequence of the  current
       locale. Each name shall start on a separate line, using the format:

              "%s=%s\n", <name>, <value>

       The  value  string  shall  be written with appropriate quoting; see the
       description of shell quoting in Quoting . The output shall be  suitable
       for reinput to the shell, setting or resetting, as far as possible, the
       variables that are currently set; read-only variables cannot be  reset.

       When  options  are specified, they shall set or unset attributes of the
       shell, as described below. When arguments  are  specified,  they  cause
       positional  parameters  to be set or unset, as described below. Setting
       or unsetting attributes and positional parameters are  not  necessarily
       related  actions,  but  they  can be combined in a single invocation of
       set.

       The set special built-in shall support the Base Definitions  volume  of
       IEEE Std 1003.1-2001,  Section  12.2,  Utility Syntax Guidelines except
       that options can be specified with either  a  leading  hyphen  (meaning
       enable  the  option) or plus sign (meaning disable it) unless otherwise
       specified.

       Implementations shall support the options in the following list in both
       their  hyphen  and plus-sign forms. These options can also be specified
       as options to sh.

       -a     When this option is on, the export attribute shall  be  set  for
              each  variable to which an assignment is performed; see the Base
              Definitions  volume  of  IEEE Std 1003.1-2001,   Section   4.21,
              Variable  Assignment.  If the assignment precedes a utility name
              in a command, the export attribute  shall  not  persist  in  the
              current  execution environment after the utility completes, with
              the  exception  that  preceding  one  of  the  special  built-in
              utilities  causes  the  export  attribute  to  persist after the
              built-in has completed. If the assignment  does  not  precede  a
              utility name in the command, or if the assignment is a result of
              the operation of the  getopts  or  read  utilities,  the  export
              attribute shall persist until the variable is unset.

       -b     This  option  shall  be supported if the implementation supports
              the User Portability Utilities option. It shall cause the  shell
              to notify the user asynchronously of background job completions.
              The following message is written to standard error:

              "[%d]%c %s%s\n", <job-number>, <current>, <status>, <job-name>

       where the fields shall be as follows:

       <current>
              The character ’+’ identifies the job that would  be  used  as  a
              default  for  the  fg  or  bg  utilities;  this  job can also be
              specified using the job_id "%+" or  "%%"  .  The  character  ’-’
              identifies  the job that would become the default if the current
              default job were to exit; this job can also be  specified  using
              the  job_id  "%-"  . For other jobs, this field is a <space>. At
              most one job can be identified with ’+’ and at most one job  can
              be identified with ’-’ . If there is any suspended job, then the
              current job shall be a suspended job. If there are at least  two
              suspended  jobs, then the previous job also shall be a suspended
              job.

       <job-number>
              A number that can be used to identify the process group  to  the
              wait, fg, bg, and kill utilities. Using these utilities, the job
              can be identified by prefixing the job number with ’%’ .

       <status>
              Unspecified.

       <job-name>
              Unspecified.

       When the shell notifies the user a  job  has  been  completed,  it  may
       remove the job’s process ID from the list of those known in the current
       shell execution environment;  see  Asynchronous  Lists  .  Asynchronous
       notification shall not be enabled by default.

       -C     (Uppercase  C.) Prevent existing files from being overwritten by
              the shell’s ’>’ redirection operator (see Redirecting Output  );
              the  ">|"  redirection  operator  shall  override this noclobber
              option for an individual file.

       -e     When this option is on, if a simple command fails for any of the
              reasons  listed  in  Consequences  of Shell Errors or returns an
              exit status value >0, and is  not  part  of  the  compound  list
              following a while, until, or if keyword, and is not a part of an
              AND or OR list, and is not a pipeline preceded by the ! reserved
              word, then the shell shall immediately exit.

       -f     The shell shall disable pathname expansion.

       -h     Locate  and  remember  utilities  invoked  by functions as those
              functions are defined (the utilities are normally  located  when
              the function is executed).

       -m     This  option  shall  be supported if the implementation supports
              the User Portability Utilities option. All jobs shall be run  in
              their  own process groups. Immediately before the shell issues a
              prompt  after  completion  of  the  background  job,  a  message
              reporting the exit status of the background job shall be written
              to standard error. If a foreground job stops,  the  shell  shall
              write  a  message to standard error to that effect, formatted as
              described by the jobs utility.  In addition, if  a  job  changes
              status other than exiting (for example, if it stops for input or
              output or is stopped by a SIGSTOP signal), the shell shall write
              a  similar message immediately prior to writing the next prompt.
              This option is enabled by default for interactive shells.

       -n     The shell shall read commands but does not  execute  them;  this
              can  be  used  to  check  for  shell  script  syntax  errors. An
              interactive shell may ignore this option.

       -o     Write the current settings of the options to standard output  in
              an unspecified format.

       +o     Write the current option settings to standard output in a format
              that is suitable for reinput  to  the  shell  as  commands  that
              achieve the same options settings.

       -o  option

              This  option  is  supported  if  the  system  supports  the User
              Portability Utilities option. It shall set various options, many
              of  which  shall be equivalent to the single option letters. The
              following values of option shall be supported:

       allexport
              Equivalent to -a.

       errexit
              Equivalent to -e.

       ignoreeof
              Prevent an interactive shell from exiting on  end-of-file.  This
              setting prevents accidental logouts when <control>-D is entered.
              A user shall explicitly exit to leave the interactive shell.

       monitor
              Equivalent to  -m.  This  option  is  supported  if  the  system
              supports the User Portability Utilities option.

       noclobber
              Equivalent to -C (uppercase C).

       noglob
              Equivalent to -f.

       noexec
              Equivalent to -n.

       nolog
              Prevent  the  entry  of  function  definitions  into the command
              history; see Command History List .

       notify
              Equivalent to -b.

       nounset
              Equivalent to -u.

       verbose
              Equivalent to -v.

       vi
              Allow shell command line editing using the built-in  vi  editor.
              Enabling  vi  mode  shall disable any other command line editing
              mode provided as an implementation extension.

              It need not be possible to set vi mode on for certain block-mode
              terminals.

       xtrace
              Equivalent to -x.

       -u     The  shell shall write a message to standard error when it tries
              to expand a variable that is not set and  immediately  exit.  An
              interactive shell shall not exit.

       -v     The shell shall write its input to standard error as it is read.

       -x     The shell shall write to standard error a trace for each command
              after  it  expands  the command and before it executes it. It is
              unspecified whether  the  command  that  turns  tracing  off  is
              traced.

       The  default  for  all these options shall be off (unset) unless stated
       otherwise in the description of the option  or  unless  the  shell  was
       invoked with them on; see sh.

       The  remaining  arguments  shall be assigned in order to the positional
       parameters. The special parameter ’#’  shall  be  set  to  reflect  the
       number  of  positional  parameters.  All positional parameters shall be
       unset before any new values are assigned.

       The special argument "--" immediately following the  set  command  name
       can  be used to delimit the arguments if the first argument begins with
       ’+’ or ’-’ , or to prevent inadvertent listing of all  shell  variables
       when  there are no arguments. The command set -- without argument shall
       unset all positional parameters and set the special  parameter  ’#’  to
       zero.

OPTIONS

       See the DESCRIPTION.

OPERANDS

       See the DESCRIPTION.

STDIN

       Not used.

INPUT FILES

       None.

ENVIRONMENT VARIABLES

       None.

ASYNCHRONOUS EVENTS

       Default.

STDOUT

       See the DESCRIPTION.

STDERR

       The standard error shall be used only for diagnostic messages.

OUTPUT FILES

       None.

EXTENDED DESCRIPTION

       None.

EXIT STATUS

       Zero.

CONSEQUENCES OF ERRORS

       Default.

       The following sections are informative.

APPLICATION USAGE

       None.

EXAMPLES

       Write out all variables and their values:

              set

       Set $1, $2, and $3 and set "$#" to 3:

              set c a b

       Turn on the -x and -v options:

              set -xv

       Unset all positional parameters:

              set --

       Set $1 to the value of x, even if it begins with ’-’ or ’+’ :

              set -- "$x"

       Set  the positional parameters to the expansion of x, even if x expands
       with a leading ’-’ or ’+’ :

              set -- $x

RATIONALE

       The set -- form is listed specifically in the SYNOPSIS even though this
       usage  is  implied by the Utility Syntax Guidelines. The explanation of
       this feature removes any ambiguity about whether the set -- form  might
       be  misinterpreted  as  being  equivalent to set without any options or
       arguments. The functionality of this form has  been  adopted  from  the
       KornShell.  In  System  V, set -- only unsets parameters if there is at
       least one argument; the only way to unset  all  parameters  is  to  use
       shift.  Using  the KornShell version should not affect System V scripts
       because there should  be  no  reason  to  issue  it  without  arguments
       deliberately; if it were issued as, for example:

              set -- "$@"

       and there were in fact no arguments resulting from "$@" , unsetting the
       parameters would have no result.

       The set + form in early proposals was omitted as being  an  unnecessary
       duplication of set alone and not widespread historical practice.

       The  noclobber option was changed to allow set -C as well as the set -o
       noclobber option. The single-letter  version  was  added  so  that  the
       historical  "$-" paradigm would not be broken; see Special Parameters .

       The -h flag is related to command name hashing and is only required  on
       XSI-conformant systems.

       The  following  set flags were omitted intentionally with the following
       rationale:

       -k     The -k flag was originally added by the  author  of  the  Bourne
              shell to make it easier for users of pre-release versions of the
              shell. In early versions of the Bourne shell the  construct  set
              name=  value had to be used to assign values to shell variables.
              The problem with  -k  is  that  the  behavior  affects  parsing,
              virtually  precluding  writing  any  compilers.  To  explain the
              behavior  of  -k,  it  is  necessary  to  describe  the  parsing
              algorithm, which is implementation-defined. For example:

              set -k; echo name=value

       and:

              set -k
              echo name=value

       behave  differently.  The  interaction  with  functions  is  even  more
       complex.  What is more, the -k flag is never needed, since the  command
       line could have been reordered.

       -t     The  -t  flag is hard to specify and almost never used. The only
              known use could  be  done  with  here-documents.  Moreover,  the
              behavior  with  ksh and sh differs. The reference page says that
              it exits after reading and executing one command.  What  is  one
              command?  If  the  input  is  date;  date, sh executes both date
              commands while ksh does only the first.

       Consideration was given to rewriting  set  to  simplify  its  confusing
       syntax. A specific suggestion was that the unset utility should be used
       to unset options instead of using the  non-  getopt()  -able  +  option
       syntax.  However,  the  conclusion  was  reached  that  the  historical
       practice of using + option was  satisfactory  and  that  there  was  no
       compelling reason to modify such widespread historical practice.

       The  -o option was adopted from the KornShell to address user needs. In
       addition to its generally friendly interface, -o is needed  to  provide
       the  vi command line editing mode, for which historical practice yields
       no single-letter option name. (Although it might have been possible  to
       invent  such a letter, it was recognized that other editing modes would
       be developed and -o provides  ample  name  space  for  describing  such
       extensions.)

       Historical  implementations  are inconsistent in the format used for -o
       option status reporting. The +o format without an  option-argument  was
       added  to  allow  portable  access to the options that can be saved and
       then later restored using, for instance, a dot script.

       Historically, sh did trace the command set +x, but ksh did not.

       The ignoreeof setting prevents accidental logouts when the  end-of-file
       character  (typically  <control>-D) is entered. A user shall explicitly
       exit to leave the interactive shell.

       The set -m option was added to apply only to the UPE because it applies
       primarily to interactive use, not shell script applications.

       The  ability  to  do  asynchronous notification became available in the
       1988 version of the KornShell. To have it occur, the user had to  issue
       the command:

              trap "jobs -n" CLD

       The   C   shell  provides  two  different  levels  of  an  asynchronous
       notification capability. The environment variable notify  is  analogous
       to  what  is done in set -b or set -o notify. When set, it notifies the
       user immediately  of  background  job  completions.  When  unset,  this
       capability is turned off.

       The  other  notification  ability  comes  through  the built-in utility
       notify. The syntax is:

              notify [%job ... ]

       By issuing notify with no operands, it causes the C shell to notify the
       user asynchronously when the state of the current job changes. If given
       operands, notify asynchronously informs the  user  of  changes  in  the
       states of the specified jobs.

       To  add  asynchronous  notification  to  the  POSIX  shell, neither the
       KornShell extensions to  trap,  nor  the  C  shell  notify  environment
       variable  seemed appropriate ( notify is not a proper POSIX environment
       variable name).

       The set -b option was selected as a compromise.

       The notify built-in was considered to have more functionality than  was
       required for simple asynchronous notification.

FUTURE DIRECTIONS

       None.

SEE ALSO

       Special Built-In Utilities

COPYRIGHT

       Portions  of  this text are reprinted and reproduced in electronic form
       from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
       --  Portable  Operating  System  Interface (POSIX), The Open Group Base
       Specifications Issue 6, Copyright (C) 2001-2003  by  the  Institute  of
       Electrical  and  Electronics  Engineers, Inc and The Open Group. In the
       event of any discrepancy between this version and the original IEEE and
       The  Open Group Standard, the original IEEE and The Open Group Standard
       is the referee document. The original Standard can be  obtained  online
       at http://www.opengroup.org/unix/online.html .