Unix/Linux Go Back    


Linux 2.6 - man page for set (linux section 1posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


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

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 nec-
       essarily 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 preced-
	      ing 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 Asynchro-
       nous Lists . Asynchronous notification shall not be enabled by default.

       -C     (Uppercase C.) Prevent existing files from being overwritten by the shell's '>' re-
	      direction  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  immedi-
	      ately  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 for-
	      mat.

       +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 sin-
	      gle 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 Porta-
	      bility 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 vari-
	      able 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 spe-
       cial parameter '#' shall be set to reflect the number of positional parameters. All  posi-
       tional 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  inad-
       vertent	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 Korn-
       Shell. 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 bro-
       ken; see Special Parameters .

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

       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  eas-
	      ier 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  vari-
	      ables. The problem with -k is that the behavior affects parsing, virtually preclud-
	      ing 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 ref-
	      erence 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 sug-
       gestion	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 histori-
       cal 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  (typi-
       cally  <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 asyn-
       chronously when the state of the current job changes.  If  given  operands,  notify  asyn-
       chronously 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 orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					   SET(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 07:46 AM.