Man Pages

set(1p) - phpMan set(1p) - phpMan

Command: man perldoc info search(apropos)  


SET(1P)                    POSIX Programmer's Manual                   SET(1P)



PROLOG
       This manual page is part of the POSIX Programmer's Manual.  The Linux implementation of this interface may dif-
       fer (consult the corresponding Linux manual page for details of Linux behavior), or the interface  may  not  be
       implemented on Linux.

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, Util-
       ity 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 com-
              pletion of the background job, a message reporting the exit status of the background job shall be  writ-
              ten  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 syn-
              tax 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 var-
              ious 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 misin-
       terpreted 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 ver-
       sion 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  pars-
              ing,  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-docu-
              ments. Moreover, the behavior with ksh and sh differs. The reference page says that it exits after read-
              ing  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. How-
       ever, 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 notifi-
       cation.

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, Stan-
       dard for Information Technology -- Portable Operating System Interface (POSIX), The Open Group Base  Specifica-
       tions  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 Stan-
       dard,  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 .



IEEE/The Open Group                  2003                              SET(1P)