Penguin
Recent Changes
Blame: bash(1)Part7
EditPageHistoryDiffInfoLikePages
Annotated edit history of bash(1)Part7 version 1, including all changes. View license author blame.
Rev Author # Line
1 JohnMcPherson 1 !!BASH MAN PAGE (Part 7)
2
3 __Navigation__%%%
4 This man page has been split into 7 pages:%%%
5 bash(1)
6 * NAME
7 * SYNOPSIS
8 * COPYRIGHT
9 * DESCRIPTION
10 * OPTIONS
11 * ARGUMENTS
12 * INVOCATION
13
14 [bash(1)Part2]
15 * DEFINITIONS
16 * RESERVED WORDS
17 * SHELL GRAMMAR
18 * COMMENTS
19 * QUOTING
20
21 [bash(1)Part3]
22 * PARAMETERS
23
24 [bash(1)Part4]
25 * EXPANSION
26
27 [bash(1)Part5]
28 * REDIRECTION
29 * ALIASES
30 * FUNCTIONS
31 * ARITHMETIC EVALUATION
32 * CONDITIONAL EXPRESSIONS
33 * SIMPLE COMMAND EXPANSION
34 * COMMAND EXECUTION
35 * COMMAND EXECUTION ENVIRONMENT
36 * ENVIRONMENT
37 * EXIT STATUS
38 * SIGNALS
39 * JOB CONTROL
40 * PROMPTING
41
42 [bash(1)Part6]
43 * READLINE
44 * HISTORY
45 * HISTORY EXPANSION
46
47
48 __Part7__
49 * SHELL BUILTIN COMMANDS
50 * RESTRICTED SHELL
51 * SEE ALSO
52 * FILES
53 * AUTHORS
54 * BUG REPORTS
55 * BUGS
56
57 ----
58 !!SHELL BUILTIN COMMANDS
59
60 Unless otherwise noted, each builtin command documented in this section as accepting options preceded by __-__ accepts __-__ to signify the end of the options.
61
62
63
64 __:__ [[''arguments'']
65 ;:
66
67 No effect; the command does nothing beyond expanding ''arguments'' and performing any specified redirections. A zero exit code is returned.
68 ;
69
70 : __ . __ ''filename'' [[''arguments'']
71 ;__source__ ''filename'' [[''arguments''] :
72
73 Read and execute commands from ''filename'' in the current shell environment and return the exit status of the last command executed from ''filename'' . If ''filename'' does not contain a slash, file names in __PATH__ are used to find the directory containing ''filename'' . The file searched for in __PATH__ need not be executable. When __bash__ is not in ''posix mode'', the current directory is searched if no file is found in __PATH__ . If the __sourcepath__ option to the __shopt__ builtin command is turned off, the __PATH__ is not searched. If any ''arguments'' are supplied, they become the positional parameters when ''filename'' is executed. Otherwise the positional parameters are unchanged. The return status is the status of the last command exited within the script (0 if no commands are executed), and false if ''filename'' is not found or cannot be read.
74 ;__alias__ [[__-p__] [[''name''[[=''value''] ...] : __Alias__ with no arguments or with the __-p__ option prints the list of aliases in the form __alias__ ''name''=''value'' on standard output. When arguments are supplied, an alias is defined for each ''name'' whose ''value'' is given. A trailing space in ''value'' causes the next word to be checked for alias substitution when the alias is expanded. For each ''name'' in the argument list for which no ''value'' is supplied, the name and value of the alias is printed. __Alias__ returns true unless a ''name'' is given for which no alias has been defined.
75 ;__bg__ [[''jobspec''] : Resume the suspended job ''jobspec'' in the background, as if it had been started with __&__ . If ''jobspec'' is not present, the shell's notion of the ''current job'' is used. __bg__ ''jobspec'' returns 0 unless run when job control is disabled or, when run with job control enabled, if ''jobspec'' was not found or started without job control.
76 ;
77
78 : __bind__ [[__-m__ ''keymap''] [[__-lpsvPSV__]
79 ;__bind__ [[__-m__ ''keymap''] [[__-q__ ''function''] [[__-u__ ''function''] [[__-r__ ''keyseq''] :
80 ;__bind__ [[__-m__ ''keymap''] __-f__ ''filename'' :
81
82 __bind__ [[__-m__ ''keymap''] __-x__ ''keyseq'':''shell-command''
83 ;:
84
85 __bind__ [[__-m__ ''keymap''] ''keyseq'':''function-name''
86 ;:
87
88 Display current __readline__ key and function bindings, or bind a key sequence to a __readline__ function or macro. The binding syntax accepted is identical to that of ''.inputrc'' , but each binding must be passed as a separate argument; e.g., '"\C-x\C-r": re-read-init-file'. Options, if supplied, have the following meanings:
89
90
91 ;__-m ''keymap''__ : Use ''keymap'' as the keymap to be affected by the subsequent bindings. Acceptable ''keymap'' names are ''emacs, emacs-standard, emacs-meta, emacs-ctlx, vi, vi-move, vi-command, and ''vi-insert'' . ''vi'' is equivalent to ''vi-command''; ''emacs'' is equivalent to ''emacs-standard''.
92 ;__-l__ : List the names of all __readline__ functions.
93 ;__-p__ : Display __readline__ function names and bindings in such a way that they can be re-read.
94 ;__-P__ : List current __readline__ function names and bindings.
95 ;__-v__ : Display __readline__ variable names and values in such a way that they can be re-read.
96 ;__-V__ : List current __readline__ variable names and values.
97 ;__-s__ : Display __readline__ key sequences bound to macros and the strings they output in such a way that they can be re-read.
98 ;__-S__ : Display __readline__ key sequences bound to macros and the strings they output.
99 ;__-f ''filename''__ : Read key bindings from ''filename''.
100 ;__-q ''function''__ : Query about which keys invoke the named ''function''.
101 ;__-u ''function''__ : Unbind all keys bound to the named ''function''.
102 ;__-r ''keyseq''__ : Remove any current binding for ''keyseq''.
103
104 __-x ''keyseq'':''shell-command''__
105 ;: Cause ''shell-command'' to be executed whenever ''keyseq'' is entered.
106
107
108
109 The return value is 0 unless an unrecognized option is given or an error occurred.
110
111 ;__break__ [[''n''] : Exit from within a __for__ , __while__ , __until__ , or __select__ loop. If ''n'' is specified, break ''n'' levels. ''n'' must be \(>= 1. If ''n'' is greater than the number of enclosing loops, all enclosing loops are exited. The return value is 0 unless the shell is not executing a loop when __break__ is executed.
112 ;__builtin__ ''shell-builtin'' [[''arguments''] : Execute the specified shell builtin, passing it ''arguments'' , and return its exit status. This is useful when defining a function whose name is the same as a shell builtin, retaining the functionality of the builtin within the function. The __cd__ builtin is commonly redefined this way. The return status is false if ''shell-builtin'' is not a shell builtin command.
113 ;__cd__ [[__-LP__] [[''dir''] : Change the current directory to ''dir''. The variable __HOME__ is the default ''dir'' . The variable __CDPATH__ defines the search path for the directory containing ''dir'' . Alternative directory names in __CDPATH__ are separated by a colon (:). A null directory name in __CDPATH__ is the same as the current directory, i.e., "__.__". If ''dir'' begins with a slash (/), then __CDPATH__ is not used. The __-P__ option says to use the physical directory structure instead of following symbolic links (see also the __-P__ option to the __set__ builtin command); the __-L__ option forces symbolic links to be followed. An argument of __-__ is equivalent to __$OLDPWD__ . The return value is true if the directory was successfully changed; false otherwise.
114 ;__command__ [[__-pVv__] ''command'' [[''arg'' ...] : Run ''command'' with ''args'' suppressing the normal shell function lookup. Only builtin commands or commands found in the __PATH__ are executed. If the __-p__ option is given, the search for ''command'' is performed using a default value for __PATH__ that is guaranteed to find all of the standard utilities. If either the __-V__ or __-v__ option is supplied, a description of ''command'' is printed. The __-v__ option causes a single word indicating the command or file name used to invoke ''command'' to be displayed; the __-V__ option produces a more verbose description. If the __-V__ or __-v__ option is supplied, the exit status is 0 if ''command'' was found, and 1 if not. If neither option is supplied and an error occurred or ''command'' cannot be found, the exit status is 127. Otherwise, the exit status of the __command__ builtin is the exit status of ''command'' .
115 ;__compgen__ [[''option''] [[''word''] : Generate possible completion matches for ''word'' according to the ''option''s, which may be any option accepted by the __complete__ builtin with the exception of __-p__ and __-r__, and write the matches to the standard output. When using the __-F__ or __-C__ options, the various shell variables set by the programmable completion facilities, while available, will not have useful values.
116
117 The matches will be generated in the same way as if the programmable completion code had generated them directly from a completion specification with the same flags. If ''word'' is specified, only those completions matching ''word'' will be displayed.
118
119 The return value is true unless an invalid option is supplied, or no matches were generated.
120 ;
121
122 : __complete__ [[__-abcdefjkvu__] [[__-o__ ''comp-option''] [[__-A__ ''action''] [[__-G__ ''globpat''] [[__-W__ ''wordlist''] [[__-P__ ''prefix''] [[__-S__ ''suffix'']
123 [[__-X__ ''filterpat''] [[__-F__ ''function''] [[__-C__ ''command''] ''name'' [[''name ...'']
124 ;__complete__ __-pr__ [[''name'' ...] :
125
126 Specify how arguments to each ''name'' should be completed. If the __-p__ option is supplied, or if no options are supplied, existing completion specifications are printed in a way that allows them to be reused as input. The __-r__ option removes a completion specification for each ''name'', or, if no ''name''s are supplied, all completion specifications.
127
128 The process of applying these completion specifications when word completion is attempted is described above under __Programmable Completion__.
129
130 Other options, if specified, have the following meanings. The arguments to the __-G__, __-W__, and __-X__ options (and, if necessary, the __-P__ and __-S__ options) should be quoted to protect them from expansion before the __complete__ builtin is invoked.
131
132
133 ;__-o__ ''comp-option'' : The ''comp-option'' controls several aspects of the compspec's behavior beyond the simple generation of completions. ''comp-option'' may be one of:
134
135 ;__default__ : Use readline's default completion if the compspec generates no matches.
136 ;__dirnames__ : Perform directory name completion if the compspec generates no matches.
137 ;__filenames__ : Tell readline that the compspec generates filenames, so it can perform any filename-specific processing (like adding a slash to directory names or suppressing trailing spaces). Intended to be used with shell functions.
138
139 ;__-A__ ''action'' : The ''action'' may be one of the following to generate a list of possible completions:
140
141 ;__alias__ : Alias names. May also be specified as __-a__.
142 ;__arrayvar__ : Array variable names.
143 ;__binding__ : __Readline__ key binding names.
144 ;__builtin__ : Names of shell builtin commands. May also be specified as __-b__.
145 ;__command__ : Command names. May also be specified as __-c__.
146 ;__directory__ : Directory names. May also be specified as __-d__.
147 ;__disabled__ : Names of disabled shell builtins.
148 ;__enabled__ : Names of enabled shell builtins.
149 ;__export__ : Names of exported shell variables. May also be specified as __-e__.
150 ;__file__ : File names. May also be specified as __-f__.
151 ;__function__ : Names of shell functions.
152 ;__helptopic__ : Help topics as accepted by the __help__ builtin.
153 ;__hostname__ : Hostnames, as taken from the file specified by the __HOSTFILE__ shell variable.
154 ;__job__ : Job names, if job control is active. May also be specified as __-j__.
155 ;__keyword__ : Shell reserved words. May also be specified as __-k__.
156 ;__running__ : Names of running jobs, if job control is active.
157 ;__setopt__ : Valid arguments for the __-o__ option to the __set__ builtin.
158 ;__shopt__ : Shell option names as accepted by the __shopt__ builtin.
159 ;__signal__ : Signal names.
160 ;__stopped__ : Names of stopped jobs, if job control is active.
161 ;__user__ : User names. May also be specified as __-u__.
162 ;__variable__ : Names of all shell variables. May also be specified as __-v__.
163
164 ;__-G__ ''globpat'' : The filename expansion pattern ''globpat'' is expanded to generate the possible completions.
165 ;__-W__ ''wordlist'' : The ''wordlist'' is split using the characters in the __IFS__ special variable as delimiters, and each resultant word is expanded. The possible completions are the members of the resultant list which match the word being completed.
166 ;__-C__ ''command'' : ''command'' is executed in a subshell environment, and its output is used as the possible completions.
167 ;__-F__ ''function'' : The shell function ''function'' is executed in the current shell environment. When it finishes, the possible completions are retrieved from the value of the __COMPREPLY__ array variable.
168 ;__-X__ ''filterpat'' : ''filterpat'' is a pattern as used for filename expansion. It is applied to the list of possible completions generated by the preceding options and arguments, and each completion matching ''filterpat'' is removed from the list. A leading __!__ in ''filterpat'' negates the pattern; in this case, any completion not matching ''filterpat'' is removed.
169 ;__-P__ ''prefix'' : ''prefix'' is added at the beginning of each possible completion after all other options have been applied.
170 ;__-S__ ''suffix'' : ''suffix'' is appended to each possible completion after all other options have been applied.
171
172
173 The return value is true unless an invalid option is supplied, an option other than __-p__ or __-r__ is supplied without a ''name'' argument, an attempt is made to remove a completion specification for a ''name'' for which no specification exists, or an error occurs adding a completion specification.
174
175 ;__continue__ [[''n''] : Resume the next iteration of the enclosing __for__ , __while__ , __until__ , or __select__ loop. If ''n'' is specified, resume at the ''n''th enclosing loop. ''n'' must be \(>= 1. If ''n'' is greater than the number of enclosing loops, the last enclosing loop (the "top-level" loop) is resumed. The return value is 0 unless the shell is not executing a loop when __continue__ is executed.
176 ;
177
178 : __declare__ [[__-afFirx__] [[__-p__] [[''name''[[=''value'']]
179 ;__typeset__ [[__-afFirx__] [[__-p__] [[''name''[[=''value'']] :
180
181 Declare variables and/or give them attributes. If no ''name''s are given then display the values of variables. The __-p__ option will display the attributes and values of each ''name'' . When __-p__ is used, additional options are ignored. The __-F__ option inhibits the display of function definitions; only the function name and attributes are printed. The __-F__ option implies __-f__ . The following options can be used to restrict output to variables with the specified attribute or to give variables attributes:
182
183
184 ;__-a__ : Each ''name'' is an array variable (see __Arrays__ above).
185 ;__-f__ : Use function names only.
186 ;__-i__ : The variable is treated as an integer; arithmetic evaluation (see __ARITHMETIC EVALUATION" ") __ is performed when the variable is assigned a value.
187 ;__-r__ : Make ''name''s readonly. These names cannot then be assigned values by subsequent assignment statements or unset.
188 ;__-x__ : Mark ''name''s for export to subsequent commands via the environment.
189
190
191
192 Using `+' instead of `-' turns off the attribute instead, with the exception that __+a__ may not be used to destroy an array variable. When used in a function, makes each ''name'' local, as with the __local__ command. The return value is 0 unless an invalid option is encountered, an attempt is made to define a function using
193 "-f foo=bar",an attempt is made to assign a value to a readonly variable, an attempt is made to assign a value to an array variable without using the compound assignment syntax (see __Arrays__ above), one of the ''names'' is not a valid shell variable name, an attempt is made to turn off readonly status for a readonly variable, an attempt is made to turn off array status for an array variable, or an attempt is made to display a non-existent function with __-f__.
194
195
196 ;__dirs [[__-clpv__] [[+''n''] [[-''n'']__ : Without options, displays the list of currently remembered directories. The default display is on a single line with directory names separated by spaces. Directories are added to the list with the __pushd__ command; the __popd__ command removes entries from the list.
197
198
199 ;__+__''n'' : Displays the ''n''th entry counting from the left of the list shown by __dirs__ when invoked without options, starting with zero.
200 ;__-__''n'' : Displays the ''n''th entry counting from the right of the list shown by __dirs__ when invoked without options, starting with zero.
201 ;__-c__ : Clears the directory stack by deleting all of the entries.
202 ;__-l__ : Produces a longer listing; the default listing format uses a tilde to denote the home directory.
203 ;__-p__ : Print the directory stack with one entry per line.
204 ;__-v__ : Print the directory stack with one entry per line, prefixing each entry with its index in the stack.
205
206
207
208 The return value is 0 unless an invalid option is supplied or ''n'' indexes beyond the end of the directory stack.
209
210 ;__disown__ [[__-ar__] [[__-h__] [[''jobspec'' ...] : Without options, each ''jobspec'' is removed from the table of active jobs. If the __-h__ option is given, each ''jobspec'' is not removed from the table, but is marked so that __SIGHUP__ is not sent to the job if the shell receives a __SIGHUP__ . If no ''jobspec'' is present, and neither the __-a__ nor the __-r__ option is supplied, the ''current job'' is used. If no ''jobspec'' is supplied, the __-a__ option means to remove or mark all jobs; the __-r__ option without a ''jobspec'' argument restricts operation to running jobs. The return value is 0 unless a ''jobspec'' does not specify a valid job.
211 ;__echo__ [[__-neE__] [[''arg'' ...] : Output the ''arg''s, separated by spaces, followed by a newline. The return status is always 0. If __-n__ is specified, the trailing newline is suppressed. If the __-e__ option is given, interpretation of the following backslash-escaped characters is enabled. The __-E__ option disables the interpretation of these escape characters, even on systems where they are interpreted by default. The __xpg_echo__ shell option may be used to dynamically determine whether or not __echo__ expands these escape characters by default. __echo__ does not interpret __-__ to mean the end of options. __echo__ interprets the following escape sequences:
212
213
214 ;__\a__ : alert (bell)
215 ;__\b__ : backspace
216 ;__\c__ : suppress trailing newline
217 ;__\e__ : an escape character
218 ;__\f__ : form feed
219 ;__\n__ : new line
220 ;__\r__ : carriage return
221 ;__\t__ : horizontal tab
222 ;__\v__ : vertical tab
223 ;__\\e__ : backslash
224 ;__\''nnn''__ : the character whose ASCII code is the octal value ''nnn'' (one to three digits)
225 ;__\x''nnn''__ : the character whose ASCII code is the hexadecimal value ''nnn'' (one to three digits)
226
227
228 ;__enable__ [[__-adnps__] [[__-f__ ''filename''] [[''name'' ...] : Enable and disable builtin shell commands. Disabling a builtin allows a disk command which has the same name as a shell builtin to be executed without specifying a full pathname, even though the shell normally searches for builtins before disk commands. If __-n__ is used, each ''name'' is disabled; otherwise, ''names'' are enabled. For example, to use the __test__ binary found via the __PATH__ instead of the shell builtin version, run
229 "enable -n test".The __-f__ option means to load the new builtin command ''name'' from shared object ''filename'' , on systems that support dynamic loading. The __-d__ option will delete a builtin previously loaded with __-f__ . If no ''name'' arguments are given, or if the __-p__ option is supplied, a list of shell builtins is printed. With no other option arguments, the list consists of all enabled shell builtins. If __-n__ is supplied, only disabled builtins are printed. If __-a__ is supplied, the list printed includes all builtins, with an indication of whether or not each is enabled. If __-s__ is supplied, the output is restricted to the POSIX ''special'' builtins. The return value is 0 unless a ''name'' is not a shell builtin or there is an error loading a new builtin from a shared object.
230 ;__eval__ [[''arg'' ...] : The ''arg''s are read and concatenated together into a single command. This command is then read and executed by the shell, and its exit status is returned as the value of __eval__ . If there are no ''args'' , or only null arguments, __eval__ returns 0.
231 ;__exec__ [[__-cl__] [[__-a__ ''name''] [[''command'' [[''arguments'']] : If ''command'' is specified, it replaces the shell. No new process is created. The ''arguments'' become the arguments to ''command''. If the __-l__ option is supplied, the shell places a dash at the beginning of the zeroth arg passed to ''command'' . This is what login(1) does. The __-c__ option causes ''command'' to be executed with an empty environment. If __-a__ is supplied, the shell passes ''name'' as the zeroth argument to the executed command. If ''command'' cannot be executed for some reason, a non-interactive shell exits, unless the shell option __execfail__ is enabled, in which case it returns failure. An interactive shell returns failure if the file cannot be executed. If ''command'' is not specified, any redirections take effect in the current shell, and the return status is 0. If there is a redirection error, the return status is 1.
232 ;__exit__ [[''n''] : Cause the shell to exit with a status of ''n''. If ''n'' is omitted, the exit status is that of the last command executed. A trap on __EXIT__ is executed before the shell terminates.
233 ;
234
235 : __export__ [[__-fn__] [[''name''[[=''word'']] ...
236 ;__export -p__ :
237
238 The supplied ''names'' are marked for automatic export to the environment of subsequently executed commands. If the __-f__ option is given, the ''names'' refer to functions. If no ''names'' are given, or if the __-p__ option is supplied, a list of all names that are exported in this shell is printed. The __-n__ option causes the export property to be removed from the named variables. __export__ returns an exit status of 0 unless an invalid option is encountered, one of the ''names'' is not a valid shell variable name, or __-f__ is supplied with a ''name'' that is not a function.
239 ;
240
241 : __fc__ [[__-e__ ''ename''] [[__-nlr__] [[''first''] [[''last'']
242 ;__fc__ __-s__ [[''pat''=''rep''] [[''cmd''] :
243
244 Fix Command. In the first form, a range of commands from ''first'' to ''last'' is selected from the history list. ''First'' and ''last'' may be specified as a string (to locate the last command beginning with that string) or as a number (an index into the history list, where a negative number is used as an offset from the current command number). If ''last'' is not specified it is set to the current command for listing (so that
245 "fc -l -10"prints the last 10 commands) and to ''first'' otherwise. If ''first'' is not specified it is set to the previous command for editing and -16 for listing.
246
247 The __-n__ option suppresses the command numbers when listing. The __-r__ option reverses the order of the commands. If the __-l__ option is given, the commands are listed on standard output. Otherwise, the editor given by ''ename'' is invoked on a file containing those commands. If ''ename'' is not given, the value of the __FCEDIT__ variable is used, and the value of __EDITOR__ if __FCEDIT__ is not set. If neither variable is set, vi is used. When editing is complete, the edited commands are echoed and executed.
248
249 In the second form, ''command'' is re-executed after each instance of ''pat'' is replaced by ''rep''. A useful alias to use with this is
250 "r=fc -s",so that typing
251 "r cc"runs the last command beginning with
252 "cc"and typing
253 "r"re-executes the last command.
254
255
256 If the first form is used, the return value is 0 unless an invalid option is encountered or ''first'' or ''last'' specify history lines out of range. If the __-e__ option is supplied, the return value is the value of the last command executed or failure if an error occurs with the temporary file of commands. If the second form is used, the return status is that of the command re-executed, unless ''cmd'' does not specify a valid history line, in which case __fc__ returns failure.
257 ;__fg__ [[''jobspec''] : Resume ''jobspec'' in the foreground, and make it the current job. If ''jobspec'' is not present, the shell's notion of the ''current job'' is used. The return value is that of the command placed into the foreground, or failure if run when job control is disabled or, when run with job control enabled, if ''jobspec'' does not specify a valid job or ''jobspec'' specifies a job that was started without job control.
258 ;__getopts__ ''optstring'' ''name'' [[''args''] : __getopts__ is used by shell procedures to parse positional parameters. ''optstring'' contains the option characters to be recognized; if a character is followed by a colon, the option is expected to have an argument, which should be separated from it by white space. The colon and question mark characters may not be used as option characters. Each time it is invoked, __getopts__ places the next option in the shell variable ''name'' , initializing ''name'' if it does not exist, and the index of the next argument to be processed into the variable __OPTIND__ . __OPTIND__ is initialized to 1 each time the shell or a shell script is invoked. When an option requires an argument, __getopts__ places that argument into the variable __OPTARG__ . The shell does not reset __OPTIND__ automatically; it must be manually reset between multiple calls to __getopts__ within the same shell invocation if a new set of parameters is to be used.
259
260 When the end of options is encountered, __getopts__ exits with a return value greater than zero. __OPTIND__ is set to the index of the first non-option argument, and __name__ is set to ?.
261
262 __getopts__ normally parses the positional parameters, but if more arguments are given in ''args'' , __getopts__ parses those instead.
263
264 __getopts__ can report errors in two ways. If the first character of ''optstring'' is a colon, ''silent'' error reporting is used. In normal operation diagnostic messages are printed when invalid options or missing option arguments are encountered. If the variable __OPTERR__ is set to 0, no error messages will be displayed, even if the first character of ''optstring'' is not a colon.
265
266 If an invalid option is seen, __getopts__ places ? into ''name'' and, if not silent, prints an error message and unsets __OPTARG__ . If __getopts__ is silent, the option character found is placed in __OPTARG__ and no diagnostic message is printed.
267
268 If a required argument is not found, and __getopts__ is not silent, a question mark (__?__) is placed in ''name'' , __OPTARG__ is unset, and a diagnostic message is printed. If __getopts__ is silent, then a colon (__:__) is placed in ''name'' and __OPTARG__ is set to the option character found.
269
270 __getopts__ returns true if an option, specified or unspecified, is found. It returns false if the end of options is encountered or an error occurs.
271 ;__hash__ [[__-r__] [[__-p__ ''filename''] [[''name''] : For each ''name'' , the full file name of the command is determined by searching the directories in __$PATH__ and remembered. If the __-p__ option is supplied, no path search is performed, and ''filename'' is used as the full file name of the command. The __-r__ option causes the shell to forget all remembered locations. If no arguments are given, information about remembered commands is printed. The return status is true unless a ''name'' is not found or an invalid option is supplied.
272 ;__help__ [[__-s__] [[''pattern''] : Display helpful information about builtin commands. If ''pattern'' is specified, __help__ gives detailed help on all commands matching ''pattern'' ; otherwise help for all the builtins and shell control structures is printed. The __-s__ option restricts the information displayed to a short usage synopsis. The return status is 0 unless no command matches ''pattern'' .
273 ;
274
275 : __history [[''n''__]
276 ;__history__ __-c__ :
277 ;__history -d__ ''offset'' :
278 ;__history__ __-anrw__ [[''filename''] :
279 ;__history__ __-p__ ''arg'' [[''arg ...''] :
280 ;__history__ __-s__ ''arg'' [[''arg ...''] :
281
282 With no options, display the command history list with line numbers. Lines listed with a __*__ have been modified. An argument of ''n'' lists only the last ''n'' lines. If ''filename'' is supplied, it is used as the name of the history file; if not, the value of __HISTFILE__ is used. Options, if supplied, have the following meanings:
283
284
285 ;__-c__ : Clear the history list by deleting all the entries.
286 ;__-d__ ''offset'' : Delete the history entry at position ''offset''.
287 ;__-a__ : Append the "new" history lines (history lines entered since the beginning of the current __bash__ session) to the history file.
288 ;__-n__ : Read the history lines not already read from the history file into the current history list. These are lines appended to the history file since the beginning of the current __bash__ session.
289 ;__-r__ : Read the contents of the history file and use them as the current history.
290 ;__-w__ : Write the current history to the history file, overwriting the history file's contents.
291 ;__-p__ : Perform history substitution on the following ''args'' and display the result on the standard output. Does not store the results in the history list. Each ''arg'' must be quoted to disable normal history expansion.
292 ;__-s__ : Store the ''args'' in the history list as a single entry. The last command in the history list is removed before the ''args'' are added.
293
294
295
296 The return value is 0 unless an invalid option is encountered, an error occurs while reading or writing the history file, an invalid ''offset'' is supplied as an argument to __-d__, or the history expansion supplied as an argument to __-p__ fails.
297
298 ;
299
300 : __jobs__ [[__-lnprs__] [[ ''jobspec'' ... ]
301 ;__jobs__ __-x__ ''command'' [[ ''args'' ... ] :
302
303 The first form lists the active jobs. The options have the following meanings:
304
305
306 ;__-l__ : List process IDs in addition to the normal information.
307 ;__-p__ : List only the process ID of the job's process group leader.
308 ;__-n__ : Display information only about jobs that have changed status since the user was last notified of their status.
309 ;__-r__ : Restrict output to running jobs.
310 ;__-s__ : Restrict output to stopped jobs.
311
312
313
314 If ''jobspec'' is given, output is restricted to information about that job. The return status is 0 unless an invalid option is encountered or an invalid ''jobspec'' is supplied.
315
316 If the __-x__ option is supplied, __jobs__ replaces any ''jobspec'' found in ''command'' or ''args'' with the corresponding process group ID, and executes ''command'' passing it ''args'' , returning its exit status.
317
318
319 ;: __kill__ [[__-s__ ''sigspec'' | __-n__ ''signum'' | __-__''sigspec''] [[''pid'' | ''jobspec''] ...
320 ;__kill__ __-l__ [[''sigspec'' | ''exit_status''] : Send the signal named by ''sigspec'' or ''signum'' to the processes named by ''pid'' or ''jobspec'' . ''sigspec'' is either a signal name such as __SIGKILL__ or a signal number; ''signum'' is a signal number. If ''sigspec'' is a signal name, the name may be given with or without the __SIG__ prefix. If ''sigspec'' is not present, then __SIGTERM__ is assumed. An argument of __-l__ lists the signal names. If any arguments are supplied when __-l__ is given, the names of the signals corresponding to the arguments are listed, and the return status is 0. The ''exit_status'' argument to __-l__ is a number specifying either a signal number or the exit status of a process terminated by a signal. __kill__ returns true if at least one signal was successfully sent, or false if an error occurs or an invalid option is encountered.
321 ;__let__ ''arg'' [[''arg'' ...] : Each ''arg'' is an arithmetic expression to be evaluated (see __ARITHMETIC EVALUATION__ ). If the last ''arg'' evaluates to 0, __let__ returns 1; 0 is returned otherwise.
322 ;__local__ [[''option''] [[''name''[[=''value''] ...] : For each argument, a local variable named ''name '' is created, and assigned ''value'' . The ''option'' can be any of the options accepted by __declare__. When __local__ is used within a function, it causes the variable ''name'' to have a visible scope restricted to that function and its children. With no operands, __local__ writes a list of local variables to the standard output. It is an error to use __local__ when not within a function. The return status is 0 unless __local__ is used outside a function, an invalid ''name'' is supplied, or ''name'' is a readonly variable.
323
324 ;__logout__ : Exit a login shell.
325 ;__popd__ [[-__n__] [[+''n''] [[-''n''] : Removes entries from the directory stack. With no arguments, removes the top directory from the stack, and performs a __cd__ to the new top directory. Arguments, if supplied, have the following meanings:
326
327
328 ;__+__''n'' : Removes the ''n''th entry counting from the left of the list shown by __dirs__ , starting with zero. For example:
329 "popd +0"removes the first directory,
330 "popd +1"the second.
331 ;__-__''n'' : Removes the ''n''th entry counting from the right of the list shown by __dirs__ , starting with zero. For example:
332 "popd -0"removes the last directory,
333 "popd -1"the next to last.
334 ;__-n__ : Suppresses the normal change of directory when removing directories from the stack, so that only the stack is manipulated.
335
336
337 If the __popd__ command is successful, a __dirs__ is performed as well, and the return status is 0. __popd__ returns false if an invalid option is encountered, the directory stack is empty, a non-existent directory stack entry is specified, or the directory change fails.
338
339 ;__printf__ ''format'' [[''arguments''] : Write the formatted ''arguments'' to the standard output under the control of the ''format''. The ''format'' is a character string which contains three types of objects: plain characters, which are simply copied to standard output, character escape sequences, which are converted and copied to the standard output, and format specifications, each of which causes printing of the next successive ''argument''. In addition to the standard ''printf''(1) formats, %b causes __printf__ to expand backslash escape sequences in the corresponding ''argument'', and %q causes __printf__ to output the corresponding ''argument'' in a format that can be reused as shell input.
340
341 The ''format'' is reused as necessary to consume all of the ''arguments''. If the ''format'' requires more ''arguments'' than are supplied, the extra format specifications behave as if a zero value or null string, as appropriate, had been supplied. The return value is zero on success, non-zero on failure.
342 ;
343
344 : __pushd__ [[__-n__] [[''dir'']
345 ;__pushd__ [[__-n__] [[+''n''] [[-''n''] :
346
347 Adds a directory to the top of the directory stack, or rotates the stack, making the new top of the stack the current working directory. With no arguments, exchanges the top two directories and returns 0, unless the directory stack is empty. Arguments, if supplied, have the following meanings:
348
349
350 ;__+__''n'' : Rotates the stack so that the ''n''th directory (counting from the left of the list shown by __dirs__ , starting with zero) is at the top.
351 ;__-__''n'' : Rotates the stack so that the ''n''th directory (counting from the right of the list shown by __dirs__ , starting with zero) is at the top.
352 ;__-n__ : Suppresses the normal change of directory when adding directories to the stack, so that only the stack is manipulated.
353 ;''dir'' : Adds ''dir'' to the directory stack at the top, making it the new current working directory.
354
355
356
357 If the __pushd__ command is successful, a __dirs__ is performed as well. If the first form is used, __pushd__ returns 0 unless the cd to ''dir'' fails. With the second form, __pushd__ returns 0 unless the directory stack is empty, a non-existent directory stack element is specified, or the directory change to the specified new current directory fails.
358
359 ;__pwd__ [[__-LP__] : Print the absolute pathname of the current working directory. The pathname printed contains no symbolic links if the __-P__ option is supplied or the __-o physical__ option to the __set__ builtin command is enabled. If the __-L__ option is used, the pathname printed may contain symbolic links. The return status is 0 unless an error occurs while reading the name of the current directory or an invalid option is supplied.
360 ;__read__ [[__-ers__] [[__-t__ ''timeout''] [[__-a__ ''aname''] [[__-p__ ''prompt''] [[__-n__ ''nchars''] [[__-d__ ''delim''] [[''name'' ...] : One line is read from the standard input, and the first word is assigned to the first ''name'' , the second word to the second ''name'' , and so on, with leftover words and their intervening separators assigned to the last ''name'' . If there are fewer words read from the standard input than names, the remaining names are assigned empty values. The characters in __IFS__ are used to split the line into words. The backslash character (__\__) may be used to remove any special meaning for the next character read and for line continuation. Options, if supplied, have the following meanings:
361
362
363 ;__-a ''aname''__ : The words are assigned to sequential indices of the array variable ''aname'' , starting at 0. ''aname'' is unset before any new values are assigned. Other ''name'' arguments are ignored.
364 ;__-d ''delim''__ : The first character of ''delim'' is used to terminate the input line, rather than newline.
365 ;__-e__ : If the standard input is coming from a terminal, __readline__ (see __READLINE__ above) is used to obtain the line.
366 ;__-n ''nchars''__ : __read__ returns after reading ''nchars'' characters rather than waiting for a complete line of input.
367 ;__-p ''prompt''__ : Display ''prompt'', without a trailing newline, before attempting to read any input. The prompt is displayed only if input is coming from a terminal.
368 ;__-r__ : Backslash does not act as an escape character. The backslash is considered to be part of the line. In particular, a backslash-newline pair may not be used as a line continuation.
369 ;__-s__ : Silent mode. If input is coming from a terminal, characters are not echoed.
370 ;__-t ''timeout''__ : Cause __read__ to time out and return failure if a complete line of input is not read within ''timeout'' seconds. This option has no effect if __read__ is not reading input from the terminal or a pipe.
371
372
373
374 If no ''names'' are supplied, the line read is assigned to the variable __REPLY__ . The return code is zero, unless end-of-file is encountered or __read__ times out.
375
376 ;__readonly__ [[__-apf__] [[''name'' ...] :
377
378 The given ''names'' are marked readonly; the values of these ''names'' may not be changed by subsequent assignment. If the __-f__ option is supplied, the functions corresponding to the ''names'' are so marked. The __-a__ option restricts the variables to arrays. If no ''name'' arguments are given, or if the __-p__ option is supplied, a list of all readonly names is printed. The __-p__ option causes output to be displayed in a format that may be reused as input. The return status is 0 unless an invalid option is encountered, one of the ''names'' is not a valid shell variable name, or __-f__ is supplied with a ''name'' that is not a function.
379 ;__return__ [[''n''] : Causes a function to exit with the return value specified by ''n'' . If ''n'' is omitted, the return status is that of the last command executed in the function body. If used outside a function, but during execution of a script by the __.__ (__source__) command, it causes the shell to stop executing that script and return either ''n'' or the exit status of the last command executed within the script as the exit status of the script. If used outside a function and not during execution of a script by __.__, the return status is false.
380 ;__set__ [[__-abefhkmnptuvxBCHP__] [[__-o__ ''option''] [[''arg'' ...] : Without options, the name and value of each shell variable are displayed in a format that can be reused as input. The output is sorted according to the current locale. When options are specified, they set or unset shell attributes. Any arguments remaining after the options are processed are treated as values for the positional parameters and are assigned, in order, to __$1__ , __$2__ , __...__ __$''n''__ . Options, if specified, have the following meanings:
381
382
383 ;__-a__ : Automatically mark variables and functions which are modified or created for export to the environment of subsequent commands.
384 ;__-b__ : Report the status of terminated background jobs immediately, rather than before the next primary prompt. This is effective only when job control is enabled.
385 ;__-e__ : Exit immediately if a ''simple command'' (see __SHELL GRAMMAR__ above) exits with a non-zero status. The shell does not exit if the command that fails is part of an ''until'' or ''while'' loop, part of an ''if'' statement, part of a __&&__ or __\(bv\(bv__ list, or if the command's return value is being inverted via __!__ .
386 ;__-f__ : Disable pathname expansion.
387 ;__-h__ : Remember the location of commands as they are looked up for execution. This is enabled by default.
388 ;__-k__ : All arguments in the form of assignment statements are placed in the environment for a command, not just those that precede the command name.
389 ;__-m__ : Monitor mode. Job control is enabled. This option is on by default for interactive shells on systems that support it (see __JOB CONTROL__ above). Background processes run in a separate process group and a line containing their exit status is printed upon their completion.
390 ;__-n__ : Read commands but do not execute them. This may be used to check a shell script for syntax errors. This is ignored by interactive shells.
391 ;__-o ''option-name''__ : The ''option-name'' can be one of the following:
392
393 ;__allexport__ : Same as __-a__ .
394 ;__braceexpand__ : Same as __-B__ .
395 ;__emacs__ : Use an emacs-style command line editing interface. This is enabled by default when the shell is interactive, unless the shell is started with the __-noediting__ option.
396 ;__errexit__ : Same as __-e__ .
397 ;__hashall__ : Same as __-h__ .
398 ;__histexpand__ : Same as __-H__ .
399 ;__history__ : Enable command history, as described above under __HISTORY__ . This option is on by default in interactive shells.
400 ;__ignoreeof__ : The effect is as if the shell command
401 "IGNOREEOF=10"had been executed (see __Shell Variables__ above).
402 ;__keyword__ : Same as __-k__ .
403 ;__monitor__ : Same as __-m__ .
404 ;__noclobber__ : Same as __-C__ .
405 ;__noexec__ : Same as __-n__ .
406 ;__noglob__ : Same as __-f__ .
407 ;__notify__ : Same as __-b__ .
408 ;__nounset__ : Same as __-u__ .
409 ;__onecmd__ : Same as __-t__ .
410 ;__physical__ : Same as __-P__ .
411 ;__posix__ : Change the behavior of __bash__ where the default operation differs from the POSIX 1003.2 standard to match the standard (''posix mode'').
412 ;__privileged__ : Same as __-p__ .
413 ;__verbose__ : Same as __-v__ .
414 ;__vi__ : Use a vi-style command line editing interface.
415 ;__xtrace__ : Same as __-x__ .
416
417
418
419 If __-o__ is supplied with no ''option-name'', the values of the current options are printed. If __+o__ is supplied with no ''option-name'', a series of __set__ commands to recreate the current option settings is displayed on the standard output.
420
421 ;__-p__ : Turn on ''privileged'' mode. In this mode, the __$ENV__ and __$BASH_ENV__ files are not processed, shell functions are not inherited from the environment, and the __SHELLOPTS__ variable, if it appears in the environment, is ignored. If the shell is started with the effective user (group) id not equal to the real user (group) id, and the __-p__ option is not supplied, these actions are taken and the effective user id is set to the real user id. If the __-p__ option is supplied at startup, the effective user id is not reset. Turning this option off causes the effective user and group ids to be set to the real user and group ids.
422 ;__-t__ : Exit after reading and executing one command.
423 ;__-u__ : Treat unset variables as an error when performing parameter expansion. If expansion is attempted on an unset variable, the shell prints an error message, and, if not interactive, exits with a non-zero status.
424 ;__-v__ : Print shell input lines as they are read.
425 ;__-x__ : After expanding each ''simple command'', display the expanded value of __PS4__ , followed by the command and its expanded arguments.
426 ;__-B__ : The shell performs brace expansion (see __Brace Expansion__ above). This is on by default.
427 ;__-C__ : If set, __bash__ does not overwrite an existing file with the __>__ , __>&__ , and __<>__ redirection operators. This may be overridden when creating output files by using the redirection operator __>|__ instead of __>__ .
428 ;__-H__ : Enable __!__ style history substitution. This option is on by default when the shell is interactive.
429 ;__-P__ : If set, the shell does not follow symbolic links when executing commands such as __cd__ that change the current working directory. It uses the physical directory structure instead. By default, __bash__ follows the logical chain of directories when performing commands which change the current directory.
430 ;__--__ : If no arguments follow this option, then the positional parameters are unset. Otherwise, the positional parameters are set to the ''arg''s, even if some of them begin with a __-__ .
431 ;__-__ : Signal the end of options, cause all remaining ''arg''s to be assigned to the positional parameters. The __-x__ and __-v__ options are turned off. If there are no ''arg''s, the positional parameters remain unchanged.
432
433
434 The options are off by default unless otherwise noted. Using + rather than - causes these options to be turned off. The options can also be specified as arguments to an invocation of the shell. The current set of options may be found in __$-__ . The return status is always true unless an invalid option is encountered.
435
436 ;__shift__ [[''n''] : The positional parameters from ''n''+1 ... are renamed to __$1__ __....__ Parameters represented by the numbers __$#__ down to __$#__-''n''+1 are unset. ''n'' must be a non-negative number less than or equal to __$#__. If ''n'' is 0, no parameters are changed. If ''n '' is not given, it is assumed to be 1. If ''n'' is greater than __$#__, the positional parameters are not changed. The return status is greater than zero if ''n'' is greater than __$#__ or less than zero; otherwise 0.
437 ;__shopt__ [[__-pqsu__] [[__-o__] [[''optname'' ...] : Toggle the values of variables controlling optional shell behavior. With no options, or with the __-p__ option, a list of all settable options is displayed, with an indication of whether or not each is set. The __-p__ option causes output to be displayed in a form that may be reused as input. Other options have the following meanings:
438
439
440 ;__-s__ : Enable (set) each ''optname''.
441 ;__-u__ : Disable (unset) each ''optname''.
442 ;__-q__ : Suppresses normal output (quiet mode); the return status indicates whether the ''optname'' is set or unset. If multiple ''optname'' arguments are given with __-q__ , the return status is zero if all ''optnames'' are enabled; non-zero otherwise.
443 ;__-o__ : Restricts the values of ''optname'' to be those defined for the __-o__ option to the __set__ builtin.
444
445
446
447 If either __-s__ or __-u__ is used with no ''optname'' arguments, the display is limited to those options which are set or unset, respectively. Unless otherwise noted, the __shopt__ options are disabled (unset) by default.
448
449 The return status when listing options is zero if all ''optnames'' are enabled, non-zero otherwise. When setting or unsetting options, the return status is zero unless an ''optname'' is not a valid shell option.
450
451 The list of __shopt__ options is:
452
453 ;__cdable_vars__ : If set, an argument to the __cd__ builtin command that is not a directory is assumed to be the name of a variable whose value is the directory to change to.
454 ;__cdspell__ : If set, minor errors in the spelling of a directory component in a __cd__ command will be corrected. The errors checked for are transposed characters, a missing character, and one character too many. If a correction is found, the corrected file name is printed, and the command proceeds. This option is only used by interactive shells.
455 ;__checkhash__ : If set, __bash__ checks that a command found in the hash table exists before trying to execute it. If a hashed command no longer exists, a normal path search is performed.
456 ;__checkwinsize__ : If set, __bash__ checks the window size after each command and, if necessary, updates the values of __LINES__ and __COLUMNS__ .
457 ;__cmdhist__ : If set, __bash__ attempts to save all lines of a multiple-line command in the same history entry. This allows easy re-editing of multi-line commands.
458 ;__dotglob__ : If set, __bash__ includes filenames beginning with a `.' in the results of pathname expansion.
459 ;__execfail__ : If set, a non-interactive shell will not exit if it cannot execute the file specified as an argument to the __exec__ builtin command. An interactive shell does not exit if __exec__ fails.
460 ;__expand_aliases__ : If set, aliases are expanded as described above under __ALIASES__ . This option is enabled by default for interactive shells.
461 ;__extglob__ : If set, the extended pattern matching features described above under __Pathname Expansion__ are enabled.
462 ;__histappend__ : If set, the history list is appended to the file named by the value of the __HISTFILE__ variable when the shell exits, rather than overwriting the file.
463 ;__histreedit__ : If set, and __readline__ is being used, a user is given the opportunity to re-edit a failed history substitution.
464 ;__histverify__ : If set, and __readline__ is being used, the results of history substitution are not immediately passed to the shell parser. Instead, the resulting line is loaded into the __readline__ editing buffer, allowing further modification.
465 ;__hostcomplete__ : If set, and __readline__ is being used, __bash__ will attempt to perform hostname completion when a word containing a __@__ is being completed (see __Completing__ under __READLINE__ above). This is enabled by default.
466 ;__huponexit__ : If set, __bash__ will send __SIGHUP__ to all jobs when an interactive login shell exits.
467 ;__interactive_comments__ : If set, allow a word beginning with __#__ to cause that word and all remaining characters on that line to be ignored in an interactive shell (see __COMMENTS__ above). This option is enabled by default.
468 ;__lithist__ : If set, and the __cmdhist__ option is enabled, multi-line commands are saved to the history with embedded newlines rather than using semicolon separators where possible.
469 ;__mailwarn__ : If set, and a file that __bash__ is checking for mail has been accessed since the last time it was checked, the message "The mail in ''mailfile'' has been read" is displayed.
470 ;__no_empty_cmd_completion__ : If set, and __readline__ is being used, __bash__ will not attempt to search the __PATH__ for possible completions when completion is attempted on an empty line.
471 ;__nocaseglob__ : If set, __bash__ matches filenames in a case-insensitive fashion when performing pathname expansion (see __Pathname Expansion__ above).
472 ;__nullglob__ : If set, __bash__ allows patterns which match no files (see __Pathname Expansion__ above) to expand to a null string, rather than themselves.
473 ;__progcomp__ : If set, the programmable completion facilities (see __Programmable Completion__ above) are enabled. This option is enabled by default.
474 ;__promptvars__ : If set, prompt strings undergo variable and parameter expansion after being expanded as described in __PROMPTING__ above. This option is enabled by default.
475 ;__restricted_shell__ : The shell sets this option if it is started in restricted mode (see __RESTRICTED SHELL__ below). The value may not be changed. This is not reset when the startup files are executed, allowing the startup files to discover whether or not a shell is restricted.
476 ;__shift_verbose__ : If set, the __shift__ builtin prints an error message when the shift count exceeds the number of positional parameters.
477 ;__sourcepath__ : If set, the __source__ (__.__) builtin uses the value of __PATH__ to find the directory containing the file supplied as an argument. This option is enabled by default.
478 ;__xpg_echo__ : If set, the __echo__ builtin expands backslash-escape sequences by default.
479
480 ;__suspend__ [[__-f__] : Suspend the execution of this shell until it receives a __SIGCONT__ signal. The __-f__ option says not to complain if this is a login shell; just suspend anyway. The return status is 0 unless the shell is a login shell and __-f__ is not supplied, or if job control is not enabled.
481 ;
482
483 : __test__ ''expr''
484 ;__[[__ ''expr'' __]__ : Return a status of 0 or 1 depending on the evaluation of the conditional expression ''expr'' . Each operator and operand must be a separate argument. Expressions are composed of the primaries described above under __CONDITIONAL EXPRESSIONS__ .
485 .sp 1Expressions may be combined using the following operators, listed in decreasing order of precedence.
486
487
488 ;__! ''expr''__ : True if ''expr'' is false.
489 ;__( ''expr'' )__ : Returns the value of ''expr''. This may be used to override the normal precedence of operators.
490 ;''expr1'' -__a__ ''expr2'' : True if both ''expr1'' and ''expr2'' are true.
491 ;''expr1'' -__o__ ''expr2'' : True if either ''expr1'' or ''expr2'' is true.
492
493
494
495 __test__ and __[[__ evaluate conditional expressions using a set of rules based on the number of arguments.
496
497 ;0 arguments : The expression is false.
498 ;1 argument : The expression is true if and only if the argument is not null.
499 ;2 arguments : If the first argument is __!__, the expression is true if and only if the second argument is null. If the first argument is one of the unary conditional operators listed above under __CONDITIONAL EXPRESSIONS__ , the expression is true if the unary test is true. If the first argument is not a valid unary conditional operator, the expression is false.
500 ;3 arguments : If the second argument is one of the binary conditional operators listed above under __CONDITIONAL EXPRESSIONS__ , the result of the expression is the result of the binary test using the first and third arguments as operands. If the first argument is __!__, the value is the negation of the two-argument test using the second and third arguments. If the first argument is exactly __(__ and the third argument is exactly __)__, the result is the one-argument test of the second argument. Otherwise, the expression is false. The __-a__ and __-o__ operators are considered binary operators in this case.
501 ;4 arguments : If the first argument is __!__, the result is the negation of the three-argument expression composed of the remaining arguments. Otherwise, the expression is parsed and evaluated according to precedence using the rules listed above.
502 ;5 or more arguments : The expression is parsed and evaluated according to precedence using the rules listed above.
503
504
505
506 ;__times__ : Print the accumulated user and system times for the shell and for processes run from the shell. The return status is 0.
507 ;__trap__ [[__-lp__] [[''arg''] [[''sigspec'' ...] : The command ''arg'' is to be read and executed when the shell receives signal(s) ''sigspec'' . If ''arg'' is absent or __-__ , all specified signals are reset to their original values (the values they had upon entrance to the shell). If ''arg'' is the null string the signal specified by each ''sigspec'' is ignored by the shell and by the commands it invokes. If ''arg'' is not present and __-p__ has been supplied, then the trap commands associated with each ''sigspec'' are displayed. If no arguments are supplied or if only __-p__ is given, __trap__ prints the list of commands associated with each signal number. Each ''sigspec'' is either a signal name defined in <''signal.h''>, or a signal number. If a ''sigspec'' is EXIT(0) the command ''arg'' is executed on exit from the shell. If a ''sigspec'' is __DEBUG__ , the command ''arg'' is executed after every ''simple command'' (see __SHELL GRAMMAR__ above). The __-l__ option causes the shell to print a list of signal names and their corresponding numbers. Signals ignored upon entry to the shell cannot be trapped or reset. Trapped signals are reset to their original values in a child process when it is created. The return status is false if any ''sigspec'' is invalid; otherwise __trap__ returns true.
508 ;__type__ [[__-atp__] ''name'' [[''name'' ...] : With no options, indicate how each ''name'' would be interpreted if used as a command name. If the __-t__ option is used, __type__ prints a string which is one of ''alias'' , ''keyword'' , ''function'' , ''builtin'' , or ''file '' if ''name'' is an alias, shell reserved word, function, builtin, or disk file, respectively. If the ''name'' is not found, then nothing is printed, and an exit status of false is returned. If the __-p__ option is used, __type__ either returns the name of the disk file that would be executed if ''name'' were specified as a command name, or nothing if
509 "type -t name"would not return ''file'' . If a command is hashed, __-p__ prints the hashed value, not necessarily the file that appears first in __PATH__ . If the __-a__ option is used, __type__ prints all of the places that contain an executable named ''name'' . This includes aliases and functions, if and only if the __-p__ option is not also used. The table of hashed commands is not consulted when using __-a__ . __type__ returns true if any of the arguments are found, false if none are found.
510 ;__ulimit__ [[__-SHacdflmnpstuv__ [[''limit'']] : Provides control over the resources available to the shell and to processes started by it, on systems that allow such control. The value of ''limit'' can be a number in the unit specified for the resource, or the value __unlimited__ . The __-H__ and __-S__ options specify that the hard or soft limit is set for the given resource. A hard limit cannot be increased once it is set; a soft limit may be increased up to the value of the hard limit. If neither __-H__ nor __-S__ is specified, both the soft and hard limits are set. If ''limit'' is omitted, the current value of the soft limit of the resource is printed, unless the __-H__ option is given. When more than one resource is specified, the limit name and unit are printed before the value. Other options are interpreted as follows:
511
512 ;__-a__ : All current limits are reported
513 ;__-c__ : The maximum size of core files created
514 ;__-d__ : The maximum size of a process's data segment
515 ;__-f__ : The maximum size of files created by the shell
516 ;__-l__ : The maximum size that may be locked into memory
517 ;__-m__ : The maximum resident set size
518 ;__-n__ : The maximum number of open file descriptors (most systems do not allow this value to be set)
519 ;__-p__ : The pipe size in 512-byte blocks (this may not be set)
520 ;__-s__ : The maximum stack size
521 ;__-t__ : The maximum amount of cpu time in seconds
522 ;__-u__ : The maximum number of processes available to a single user
523 ;__-v__ : The maximum amount of virtual memory available to the shell
524
525
526
527 If ''limit'' is given, it is the new value of the specified resource (the __-a__ option is display only). If no option is given, then __-f__ is assumed. Values are in 1024-byte increments, except for __-t__ , which is in seconds, __-p__ , which is in units of 512-byte blocks, and __-n__ and __-u__ , which are unscaled values. The return status is 0 unless an invalid option is encountered, a non-numeric argument other than __unlimited__ is supplied as ''limit'', or an error occurs while setting a new limit.
528
529 ;__umask__ [[__-p__] [[__-S__] [[''mode''] : The user file-creation mask is set to ''mode'' . If ''mode'' begins with a digit, it is interpreted as an octal number; otherwise it is interpreted as a symbolic mode mask similar to that accepted by chmod(1). If ''mode'' is omitted, the current value of the mask is printed. The __-S__ option causes the mask to be printed in symbolic form; the default output is an octal number. If the __-p__ option is supplied, and ''mode'' is omitted, the output is in a form that may be reused as input. The return status is 0 if the mode was successfully changed or if no ''mode'' argument was supplied, and false otherwise.
530 ;__unalias__ [[-__a__] [[''name'' ...] : Remove each ''name'' from the list of defined aliases. If __-a__ is supplied, all alias definitions are removed. The return value is true unless a supplied ''name'' is not a defined alias.
531 ;__unset__ [[-__fv__] [[''name'' ...] : For each ''name'' , remove the corresponding variable or function. If no options are supplied, or the __-v__ option is given, each ''name'' refers to a shell variable. Read-only variables may not be unset. If __-f__ is specifed, each ''name'' refers to a shell function, and the function definition is removed. Each unset variable or function is removed from the environment passed to subsequent commands. If any of __RANDOM__ , __SECONDS__ , __LINENO__ , __HISTCMD__ , __FUNCNAME__ , __GROUPS__ , or __DIRSTACK__ are unset, they lose their special properties, even if they are subsequently reset. The exit status is true unless a ''name'' does not exist or is readonly.
532 ;__wait__ [[''n''] : Wait for the specified process and return its termination status. ''n'' may be a process ID or a job specification; if a job spec is given, all processes in that job's pipeline are waited for. If ''n'' is not given, all currently active child processes are waited for, and the return status is zero. If ''n'' specifies a non-existent process or job, the return status is 127. Otherwise, the return status is the exit status of the last process or job waited for.
533
534
535 !!RESTRICTED SHELL
536 If __bash__ is started with the name __rbash__ , or the __-r__ option is supplied at invocation, the shell becomes restricted. A restricted shell is used to set up an environment more controlled than the standard shell. It behaves identically to __bash__ with the exception that the following are disallowed or not performed:
537 * changing directories with __cd__
538 * setting or unsetting the values of __SHELL__ , __PATH__ , __ENV__ , or __BASH_ENV__
539 * specifying command names containing __/__
540 * specifying a file name containing a __/__ as an argument to the __.__ builtin command
541 * Specifying a filename containing a slash as an argument to the __-p__ option to the __hash__ builtin command
542 * importing function definitions from the shell environment at startup
543 * parsing the value of __SHELLOPTS__ from the shell environment at startup
544 * redirecting output using the >, >|, <>, >&, &>, and >> redirection operators
545 * using the __exec__ builtin command to replace the shell with another command
546 * adding or deleting builtin commands with the __-f__ and __-d__ options to the __enable__ builtin command
547 * specifying the __-p__ option to the __command__ builtin command
548 * turning off restricted mode with __set +r__ or __set +o restricted__.
549
550 These restrictions are enforced after any startup files are read.
551
552 When a command that is found to be a shell script is executed (see __COMMAND EXECUTION__ above), __rbash__ turns off any restrictions in the shell spawned to execute the script. \n(zY=1 .ig zY
553
554 !!SEE ALSO
555
556
557
558 ;''Bash Reference Manual'', Brian Fox and Chet Ramey :
559 ;''The Gnu Readline Library'', Brian Fox and Chet Ramey :
560 ;''The Gnu History Library'', Brian Fox and Chet Ramey :
561
562 ''Portable Operating System Interface (POSIX) Part 2: Shell and Utilities'', IEEE
563 ;:
564 ;''sh''(1), ''ksh''(1), ''csh''(1) :
565 ;''emacs''(1), ''vi''(1) :
566 ;''readline''(3) :
567
568
569
570 !!FILES
571
572
573 ;/bin/bash : The __bash__ executable
574 ;/etc/profile : The systemwide initialization file, executed for login shells
575 ;~/.bash_profile : The personal initialization file, executed for login shells
576 ;~/.bashrc : The individual per-interactive-shell startup file
577 ;~/.bash_logout : The individual login shell cleanup file, executed when a login shell exits
578 ;~/.inputrc : Individual ''readline'' initialization file
579
580
581
582 !!AUTHORS
583 Brian Fox, Free Software Foundation
584 bfox@gnu.org
585
586 Chet Ramey, Case Western Reserve University
587 chet@ins.CWRU.Edu
588
589 !!BUG REPORTS
590 If you find a bug in __bash,__ you should report it. But first, you should make sure that it really is a bug, and that it appears in the latest version of __bash__ that you have.
591
592 Once you have determined that a bug actually exists, use the ''bashbug'' command to submit a bug report. If you have a fix, you are encouraged to mail that as well! Suggestions and `philosophical' bug reports may be mailed to ''bug-bash@gnu.org'' or posted to the Usenet newsgroup __gnu.bash.bug__ .
593
594 ALL bug reports should include:
595
596
597 ;The version number of __bash__ :
598 ;The hardware and operating system :
599 ;The compiler used to compile :
600 ;A description of the bug behaviour :
601 ;A short script or `recipe' which exercises the bug :
602
603
604
605 ''bashbug'' inserts the first three items automatically into the template it provides for filing a bug report.
606
607 Comments and bug reports concerning this manual page should be directed to ''chet@ins.CWRU.Edu'' .
608
609 !!BUGS
610
611
612 It's too big and too slow.
613
614 There are some subtle differences between __bash__ and traditional versions of __sh__ , mostly because of the [POSIX] specification.
615
616 Aliases are confusing in some uses.
617
618 Shell builtin commands and functions are not stoppable/restartable.
619
620 Compound commands and command sequences of the form `a ; b ; c' are not handled gracefully when process suspension is attempted. When a process is stopped, the shell immediately executes the next command in the sequence. It suffices to place the sequence of commands between parentheses to force it into a subshell, which may be stopped as a unit.
621
622 Commands inside of __$(__...__)__ command substitution are not parsed until substitution is attempted. This will delay error reporting until some time after the command is entered.
623
624 Array variables may not (yet) be exported.
This page is a man page (or other imported legacy content). We are unable to automatically determine the license status of this page.