Provided by: manpages-posix_2.16-1_all bug

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 .