diff options
Diffstat (limited to 'upstream/mageia-cauldron/man1p/set.1p')
| -rw-r--r-- | upstream/mageia-cauldron/man1p/set.1p | 808 |
1 files changed, 808 insertions, 0 deletions
diff --git a/upstream/mageia-cauldron/man1p/set.1p b/upstream/mageia-cauldron/man1p/set.1p new file mode 100644 index 00000000..67a9ca57 --- /dev/null +++ b/upstream/mageia-cauldron/man1p/set.1p @@ -0,0 +1,808 @@ +'\" et +.TH SET "1P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual" +.\" +.SH PROLOG +This manual page is part of the POSIX Programmer's Manual. +The Linux implementation of this interface may differ (consult +the corresponding Linux manual page for details of Linux behavior), +or the interface may not be implemented on Linux. +.\" +.SH NAME +set +\(em set or unset options and positional parameters +.SH SYNOPSIS +.LP +.nf +set \fB[\fR-abCefhmnuvx\fB] [\fR-o \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set \fB[\fR+abCefhmnuvx\fB] [\fR+o \fIoption\fB] [\fIargument\fR...\fB]\fR +.P +set --\fB [\fIargument\fR...\fB]\fR +.P +set -o +.P +set +o +.fi +.SH DESCRIPTION +If no +.IR option s +or +.IR argument s +are specified, +.IR set +shall write the names and values of all shell variables in the collation +sequence of the current locale. Each +.IR name +shall start on a separate line, using the format: +.sp +.RS 4 +.nf + +"%s=%s\en", <\fIname\fR>, <\fIvalue\fR> +.fi +.P +.RE +.P +The +.IR value +string shall be written with appropriate quoting; see the description +of shell quoting in +.IR "Section 2.2" ", " "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. +.P +When options are specified, they shall set or unset attributes of the +shell, as described below. When +.IR argument s +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 +.IR set . +.P +The +.IR set +special built-in shall support the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +except that options can be specified with either a leading +<hyphen-minus> +(meaning enable the option) or +<plus-sign> +(meaning disable it) unless otherwise specified. +.P +Implementations shall support the options in the following list in both +their +<hyphen-minus> +and +<plus-sign> +forms. These options can also be specified as options to +.IR sh . +.IP "\fB\-a\fP" 6 +When this option is on, the +.IR export +attribute shall be set for each variable to which an assignment is +performed; see the Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.23" ", " "Variable Assignment". +If the assignment precedes a utility name in a command, the +.IR 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 +.IR 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 +.IR getopts +or +.IR read +utilities, the +.IR export +attribute shall persist until the variable is unset. +.IP "\fB\-b\fP" 6 +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: +.RS 6 +.sp +.RS 4 +.nf + +"[%d]%c %s%s\en", <\fIjob-number\fR>, <\fIcurrent\fR>, <\fRstatus\fR>, <\fRjob-name\fR> +.fi +.P +.RE +.P +where the fields shall be as follows: +.IP "<\fIcurrent\fR>" 12 +The character +.BR '+' +identifies the job that would be used as a default for the +.IR fg +or +.IR bg +utilities; this job can also be specified using the +.IR job_id +.BR \(dq%+\(dq +or +.BR \(dq%%\(dq . +The character +.BR '\-' +identifies the job that would become the +default if the current default job were to exit; this job can also be +specified using the +.IR job_id +.BR \(dq%-\(dq . +For other jobs, this field is a +<space>. +At most one job can be identified with +.BR '+' +and at most one job can be identified with +.BR '\-' . +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. +.IP "<\fIjob-number\fR>" 12 +A number that can be used to identify the process group to the +.IR wait , +.IR fg , +.IR bg , +and +.IR kill +utilities. Using these utilities, the job can be identified by +prefixing the job number with +.BR '%' . +.IP "<\fIstatus\fR>" 12 +Unspecified. +.IP "<\fIjob-name\fR>" 12 +Unspecified. +.P +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 +.IR "Section 2.9.3.1" ", " "Examples". +Asynchronous notification shall not be enabled by default. +.RE +.IP "\fB\-C\fP" 6 +(Uppercase C.) Prevent existing files from being overwritten by the +shell's +.BR '>' +redirection operator (see +.IR "Section 2.7.2" ", " "Redirecting Output"); +the +.BR \(dq>|\(dq +redirection operator shall override this +.IR noclobber +option for an individual file. +.IP "\fB\-e\fP" 6 +When this option is on, when any command fails (for any of the reasons +listed in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors" +or by returning an exit status greater than zero), the shell immediately +shall exit, as if by executing the +.IR exit +special built-in utility with no arguments, with the following exceptions: +.RS 6 +.IP " 1." 4 +The failure of any individual command in a multi-command pipeline shall +not cause the shell to exit. Only the failure of the pipeline itself +shall be considered. +.IP " 2." 4 +The +.BR \-e +setting shall be ignored when executing the compound list following the +.BR while , +.BR until , +.BR if , +or +.BR elif +reserved word, a pipeline beginning with the +.BR ! +reserved word, or any command of an AND-OR list other than the last. +.IP " 3." 4 +If the exit status of a compound command other than a subshell command +was the result of a failure while +.BR \-e +was being ignored, then +.BR \-e +shall not apply to this command. +.P +This requirement applies to the shell environment and each subshell +environment separately. For example, in: +.sp +.RS 4 +.nf + +set -e; (false; echo one) | cat; echo two +.fi +.P +.RE +.P +the +.IR false +command causes the subshell to exit without executing +.IR "echo one" ; +however, +.IR "echo two" +is executed because the exit status of the pipeline +.IR "(false; echo one) | cat" +is zero. +.RE +.IP "\fB\-f\fP" 6 +The shell shall disable pathname expansion. +.IP "\fB\-h\fP" 6 +Locate and remember utilities invoked by functions as those functions +are defined (the utilities are normally located when the function is +executed). +.IP "\fB\-m\fP" 6 +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 +.IR 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. +.IP "\fB\-n\fP" 6 +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. +.IP "\fB\-o\fP" 6 +Write the current settings of the options to standard output in an +unspecified format. +.IP "\fB+o\fP" 6 +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. +.IP "\fB\-o\ \fIoption\fR" 6 +.br +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 +.IR option +shall be supported: +.RS 6 +.IP "\fIallexport\fR" 10 +Equivalent to +.BR \-a . +.IP "\fIerrexit\fR" 10 +Equivalent to +.BR \-e . +.IP "\fIignoreeof\fR" 10 +Prevent an interactive shell from exiting on end-of-file. This setting +prevents accidental logouts when +<control>\(hyD +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.IP "\fImonitor\fR" 10 +Equivalent to +.BR \-m . +This option is supported if the system supports the User Portability +Utilities option. +.IP "\fInoclobber\fR" 10 +Equivalent to +.BR \-C +(uppercase C). +.IP "\fInoglob\fR" 10 +Equivalent to +.BR \-f . +.IP "\fInoexec\fR" 10 +Equivalent to +.BR \-n . +.IP "\fInolog\fR" 10 +Prevent the entry of function definitions into the command history; see +.IR "Command History List". +.IP "\fInotify\fR" 10 +Equivalent to +.BR \-b . +.IP "\fInounset\fR" 10 +Equivalent to +.BR \-u . +.IP "\fIverbose\fR" 10 +Equivalent to +.BR \-v . +.IP "\fIvi\fR" 10 +Allow shell command line editing using the built-in +.IR vi +editor. Enabling +.IR vi +mode shall disable any other command line editing mode provided as an +implementation extension. +.RS 10 +.P +It need not be possible to set +.IR vi +mode on for certain block-mode terminals. +.RE +.IP "\fIxtrace\fR" 10 +Equivalent to +.BR \-x . +.RE +.IP "\fB\-u\fP" 6 +When the shell tries to expand an unset parameter other than the +.BR '@' +and +.BR '*' +special parameters, it shall write a message to standard error and +the expansion shall fail with the consequences specified in +.IR "Section 2.8.1" ", " "Consequences of Shell Errors". +.IP "\fB\-v\fP" 6 +The shell shall write its input to standard error as it is read. +.IP "\fB\-x\fP" 6 +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. +.P +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 +.IR sh . +.P +The remaining arguments shall be assigned in order to the positional +parameters. The special parameter +.BR '#' +shall be set to reflect the number of positional parameters. All +positional parameters shall be unset before any new values are +assigned. +.P +If the first argument is +.BR '\-' , +the results are unspecified. +.P +The special argument +.BR \(dq--\(dq +immediately following the +.IR set +command name can be used to delimit the arguments if the first argument +begins with +.BR '+' +or +.BR '\-' , +or to prevent inadvertent listing of all shell variables when there are +no arguments. The command +.IR set +.BR \-\|\- +without +.IR argument +shall unset all positional parameters and set the special parameter +.BR '#' +to zero. +.SH OPTIONS +See the DESCRIPTION. +.SH OPERANDS +See the DESCRIPTION. +.SH STDIN +Not used. +.SH "INPUT FILES" +None. +.SH "ENVIRONMENT VARIABLES" +None. +.SH "ASYNCHRONOUS EVENTS" +Default. +.SH STDOUT +See the DESCRIPTION. +.SH STDERR +The standard error shall be used only for diagnostic messages. +.SH "OUTPUT FILES" +None. +.SH "EXTENDED DESCRIPTION" +None. +.SH "EXIT STATUS" +.IP "\00" 6 +Successful completion. +.IP >0 6 +An invalid option was specified, or an error occurred. +.SH "CONSEQUENCES OF ERRORS" +Default. +.LP +.IR "The following sections are informative." +.SH "APPLICATION USAGE" +Application writers should avoid relying on +.IR set +.BR \-e +within functions. For example, in the following script: +.sp +.RS 4 +.nf + +set -e +start() { + some_server + echo some_server started successfully +} +start || echo >&2 some_server failed +.fi +.P +.RE +.P +the +.BR \-e +setting is ignored within the function body (because the function is a +command in an AND-OR list other than the last). Therefore, if +.IR some_server +fails, the function carries on to echo +.BR \(dqsome_server started successfully\(dq , +and the exit status of the function is zero (which means +.BR \(dqsome_server failed\(dq +is not output). +.SH EXAMPLES +Write out all variables and their values: +.sp +.RS 4 +.nf + +set +.fi +.P +.RE +.P +Set $1, $2, and $3 and set +.BR \(dq$#\(dq +to 3: +.sp +.RS 4 +.nf + +set c a b +.fi +.P +.RE +.P +Turn on the +.BR \-x +and +.BR \-v +options: +.sp +.RS 4 +.nf + +set -xv +.fi +.P +.RE +.P +Unset all positional parameters: +.sp +.RS 4 +.nf + +set -- +.fi +.P +.RE +.P +Set $1 to the value of +.IR x , +even if it begins with +.BR '\-' +or +.BR '+' : +.sp +.RS 4 +.nf + +set -- "$x" +.fi +.P +.RE +.P +Set the positional parameters to the expansion of +.IR x , +even if +.IR x +expands with a leading +.BR '\-' +or +.BR '+' : +.sp +.RS 4 +.nf + +set -- $x +.fi +.P +.RE +.SH "RATIONALE" +The +.IR 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 +.IR set +\-\|\- form might be misinterpreted as being equivalent to +.IR set +without any options or arguments. The functionality of this form has +been adopted from the KornShell. In System V, +.IR set +\-\|\- only unsets parameters if there is at least one argument; +the only way to unset all parameters is to use +.IR 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: +.sp +.RS 4 +.nf + +set -- "$@" +.fi +.P +.RE +.P +and there were in fact no arguments resulting from +.BR \(dq$@\(dq , +unsetting the parameters would have no result. +.P +The +.IR set ++ form in early proposals was omitted as being an unnecessary +duplication of +.IR set +alone and not widespread historical practice. +.P +The +.IR noclobber +option was changed to allow +.IR set +.BR \-C +as well as the +.IR set +.BR \-o +.IR noclobber +option. The single-letter version was added so that the historical +.BR \(dq$-\(dq +paradigm would not be broken; see +.IR "Section 2.5.2" ", " "Special Parameters". +.P +The description of the +.BR \-e +option is intended to match the behavior of the 1988 version of the +KornShell. +.P +The +.BR \-h +flag is related to command name hashing. See +.IR "\fIhash\fR\^". +.P +The following +.IR set +flags were omitted intentionally with the following rationale: +.IP "\fB\-k\fP" 6 +The +.BR \-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 +.IR set +.IR name =\c +.IR value +had to be used to assign values to shell variables. The problem with +.BR \-k +is that the behavior affects parsing, virtually precluding writing any +compilers. To explain the behavior of +.BR \-k , +it is necessary to describe the parsing algorithm, which is +implementation-defined. For example: +.RS 6 +.sp +.RS 4 +.nf + +set -k; echo \fIname\fR=\fIvalue\fR +.fi +.P +.RE +.P +and: +.sp +.RS 4 +.nf + +set -k +echo \fIname\fP=\fIvalue\fR +.fi +.P +.RE +.P +behave differently. The interaction with functions is even more +complex. What is more, the +.BR \-k +flag is never needed, since the command line could have been +reordered. +.RE +.IP "\fB\-t\fP" 6 +The +.BR \-t +flag is hard to specify and almost never used. The only known use could +be done with here-documents. Moreover, the behavior with +.IR ksh +and +.IR sh +differs. The reference page says that it exits after reading and +executing one command. What is one command? If the input is +.IR date ;\c +.IR date , +.IR sh +executes both +.IR date +commands while +.IR ksh +does only the first. +.P +Consideration was given to rewriting +.IR set +to simplify its confusing syntax. A specific suggestion was that the +.IR unset +utility should be used to unset options instead of using the non-\c +\fIgetopt\fR()\c +-able +\c +.IR option +syntax. However, the conclusion was reached that the historical +practice of using +\c +.IR option +was satisfactory and that there was no compelling reason to modify such +widespread historical practice. +.P +The +.BR \-o +option was adopted from the KornShell to address user needs. In +addition to its generally friendly interface, +.BR \-o +is needed to provide the +.IR 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 +.BR \-o +provides ample name space for describing such extensions.) +.P +Historical implementations are inconsistent in the format used for +.BR \-o +option status reporting. The +.BR +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. +.P +Historically, +.IR sh +did trace the command +.IR set +.BR +x , +but +.IR ksh +did not. +.P +The +.IR ignoreeof +setting prevents accidental logouts when the end-of-file character +(typically +<control>\(hyD) +is entered. A user shall explicitly +.IR exit +to leave the interactive shell. +.P +The +.IR set +.BR \-m +option was added to apply only to the UPE because it applies primarily +to interactive use, not shell script applications. +.P +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: +.sp +.RS 4 +.nf + +trap "jobs -n" CLD +.fi +.P +.RE +.P +The C shell provides two different levels of an asynchronous +notification capability. The environment variable +.IR notify +is analogous to what is done in +.IR set +.BR \-b +or +.IR set +.BR \-o +.IR notify . +When set, it notifies the user immediately of background job +completions. When unset, this capability is turned off. +.P +The other notification ability comes through the built-in utility +.IR notify . +The syntax is: +.sp +.RS 4 +.nf + +notify \fB[\fR%job ... \fB]\fR +.fi +.P +.RE +.P +By issuing +.IR 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, +.IR notify +asynchronously informs the user of changes in the states of the +specified jobs. +.P +To add asynchronous notification to the POSIX shell, neither the +KornShell extensions to +.IR trap , +nor the C shell +.IR notify +environment variable seemed appropriate (\c +.IR notify +is not a proper POSIX environment variable name). +.P +The +.IR set +.BR \-b +option was selected as a compromise. +.P +The +.IR notify +built-in was considered to have more functionality than was required +for simple asynchronous notification. +.P +Historically, some shells applied the +.BR \-u +option to all parameters including +.IR $@ +and +.IR $* . +The standard developers felt that this was a misfeature since it is +normal and common for +.IR $@ +and +.IR $* +to be used in shell scripts regardless of whether they were passed any +arguments. Treating these uses as an error when no arguments are passed +reduces the value of +.BR \-u +for its intended purpose of finding spelling mistakes in variable names +and uses of unset positional parameters. +.SH "FUTURE DIRECTIONS" +None. +.SH "SEE ALSO" +.IR "Section 2.14" ", " "Special Built-In Utilities", +.IR "\fIhash\fR\^" +.P +The Base Definitions volume of POSIX.1\(hy2017, +.IR "Section 4.23" ", " "Variable Assignment", +.IR "Section 12.2" ", " "Utility Syntax Guidelines" +.\" +.SH COPYRIGHT +Portions of this text are reprinted and reproduced in electronic form +from IEEE Std 1003.1-2017, Standard for Information Technology +-- Portable Operating System Interface (POSIX), The Open Group Base +Specifications Issue 7, 2018 Edition, +Copyright (C) 2018 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 . +.PP +Any typographical or formatting errors that appear +in this page are most likely +to have been introduced during the conversion of the source files to +man page format. To report such errors, see +https://www.kernel.org/doc/man-pages/reporting_bugs.html . |