diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/bash.1 | 85 | ||||
| -rw-r--r-- | doc/bash.1~ | 101 | ||||
| -rw-r--r-- | doc/bashref.texi | 155 | ||||
| -rw-r--r-- | doc/bashref.texi~ | 138 | ||||
| -rw-r--r-- | doc/version.texi | 6 | ||||
| -rw-r--r-- | doc/version.texi~ | 6 |
6 files changed, 431 insertions, 60 deletions
@@ -5,12 +5,12 @@ .\" Case Western Reserve University .\" chet@po.cwru.edu .\" -.\" Last Change: Sat Apr 17 23:24:15 EDT 2010 +.\" Last Change: Sun May 30 17:03:08 EDT 2010 .\" .\" bash_builtins, strip all but Built-Ins section .if \n(zZ=1 .ig zZ .if \n(zY=1 .ig zY -.TH BASH 1 "2010 April 17" "GNU Bash-4.1" +.TH BASH 1 "2010 May 30" "GNU Bash-4.1" .\" .\" There's some problem with having a `@' .\" in a tagged paragraph with the BSD man macros. @@ -565,6 +565,15 @@ under .B "Shell Variables" below. .PP +When the shell is in \fIposix mode\fP, \fBtime\fP +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The +.SM +.B TIMEFORMAT +variable may be used to specify the format of +the time information. +.PP Each command in a pipeline is executed as a separate process (i.e., in a subshell). .SS Lists @@ -1881,6 +1890,11 @@ A sample value is .if t \f(CW".o:~"\fP. .if n ".o:~". .TP +.B FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. +.TP .B GLOBIGNORE A colon-separated list of patterns defining the set of filenames to be ignored by pathname expansion. @@ -3781,6 +3795,11 @@ Variables local to the function may be declared with the builtin command. Ordinarily, variables and their values are shared between the function and its caller. .PP +The \fBFUNCNEST\fP variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. +.PP If the builtin command .B return is executed in a function, the function completes and @@ -4021,7 +4040,7 @@ True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists and \fIfile1\fP does not. .TP .B \-o \fIoptname\fP -True if shell option +True if the shell option .I optname is enabled. See the list of options under the description of the @@ -4030,6 +4049,11 @@ option to the .B set builtin below. .TP +.B \-v \fIvarname\fP +True if the shell variable +.I varname +is set (has been assigned a value). +.TP .B \-z \fIstring\fP True if the length of \fIstring\fP is zero. .TP @@ -7058,10 +7082,10 @@ is greater than the number of enclosing loops, the last enclosing loop (the ``top-level'' loop) is resumed. The return value is 0 unless \fIn\fP is not greater than or equal to 1. .TP -\fBdeclare\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBdeclare\fP [\fB\-aAfFgilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD 0 .TP -\fBtypeset\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBtypeset\fP [\fB\-aAfFgilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD Declare variables and/or give them attributes. If no \fIname\fPs are given then display the values of variables. @@ -7090,6 +7114,11 @@ are displayed as well. The .B \-F option implies .BR \-f . +The +.B \-g +option forces variables to be created or modified at the global scope, +even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. The following options can be used to restrict output to variables with the specified attribute or to give variables attributes: @@ -7144,11 +7173,11 @@ turns off the attribute instead, with the exceptions that \fB+a\fP may not be used to destroy an array variable and \fB+r\fP will not remove the readonly attribute. -When used in a function, -makes each +When used in a function, makes each \fIname\fP local, as with the .B local -command. +command, +unless the \fB\-g\P option is supplied, If a variable name is followed by =\fIvalue\fP, the value of the variable is set to \fIvalue\fP. The return value is 0 unless an invalid option is encountered, @@ -8004,7 +8033,8 @@ is specified without .BR \-c , the default quantum is 5000. When \fIcallback\fP is evaluated, it is supplied the index of the next -array element to be assigned as an additional argument. +array element to be assigned and the line to be assigned to that element +as additional arguments. \fIcallback\fP is evaluated after the line is read but before the array element is assigned. .PP @@ -8068,32 +8098,49 @@ directory change fails. \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] Write the formatted \fIarguments\fP to the standard output under the control of the \fIformat\fP. +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 The \fIformat\fP 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 \fIargument\fP. -In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes +In addition to the standard \fIprintf\fP(1) format specifications, +\fBprintf\fP interprets the following extensions: +.RS +.PD 0 +.TP +.B %b +causes \fBprintf\fP to expand backslash escape sequences in the corresponding \fIargument\fP (except that \fB\ec\fP terminates output, backslashes in \fB\e\(aq\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes -beginning with \fB\e0\fP may contain up to four digits), -and \fB%q\fP causes \fBprintf\fP to output the corresponding +beginning with \fB\e0\fP may contain up to four digits). +.TP +.B %q +causes \fBprintf\fP to output the corresponding \fIargument\fP in a format that can be reused as shell input. -.sp 1 +.TP +.B %(\fIdatefmt\fP)T +causes \fBprintf\fP to output the date-time string resulting from using +\fIdatefmt\fP as a format string for \fIstrftime\fP(3). The corresponding +\fIargument\fP is an integer representing the number of seconds since the +epoch. Two special argument values may be used: -1 represents the current +time, and -2 represents the time the shell was invoked. +.PD +.PP Arguments to non-string format specifiers are treated as C constants, except that a leading plus or minus sign is allowed, and if the leading character is a single or double quote, the value is the ASCII value of the following character. -.sp 1 -The \fB\-v\fP option causes the output to be assigned to the variable -\fIvar\fP rather than being printed to the standard output. -.sp 1 +.PP The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. If the \fIformat\fP requires more \fIarguments\fP 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. +appropriate, had been supplied. +The return value is zero on success, non-zero on failure. +.RE .TP \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] .PD 0 diff --git a/doc/bash.1~ b/doc/bash.1~ index 89e4a88d..b05e721b 100644 --- a/doc/bash.1~ +++ b/doc/bash.1~ @@ -5,12 +5,12 @@ .\" Case Western Reserve University .\" chet@po.cwru.edu .\" -.\" Last Change: Sat Apr 17 23:24:15 EDT 2010 +.\" Last Change: Sat May 29 20:59:17 EDT 2010 .\" .\" bash_builtins, strip all but Built-Ins section .if \n(zZ=1 .ig zZ .if \n(zY=1 .ig zY -.TH BASH 1 "2010 April 17" "GNU Bash-4.1" +.TH BASH 1 "2010 May 29" "GNU Bash-4.1" .\" .\" There's some problem with having a `@' .\" in a tagged paragraph with the BSD man macros. @@ -565,6 +565,15 @@ under .B "Shell Variables" below. .PP +When the shell is in \fIposix mode\fP, \fBtime\fP +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The +.SM +.B TIMEFORMAT +variable may be used to specify the format of +the time information. +.PP Each command in a pipeline is executed as a separate process (i.e., in a subshell). .SS Lists @@ -1104,6 +1113,14 @@ the eight-bit character whose value is the octal value \fInnn\fP the eight-bit character whose value is the hexadecimal value \fIHH\fP (one or two hex digits) .TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) +.TP .B \ec\fIx\fP a control-\fIx\fP character .PD @@ -1873,6 +1890,11 @@ A sample value is .if t \f(CW".o:~"\fP. .if n ".o:~". .TP +.B FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. +.TP .B GLOBIGNORE A colon-separated list of patterns defining the set of filenames to be ignored by pathname expansion. @@ -3773,6 +3795,11 @@ Variables local to the function may be declared with the builtin command. Ordinarily, variables and their values are shared between the function and its caller. .PP +The \fBFUNCNEST\fP variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. +.PP If the builtin command .B return is executed in a function, the function completes and @@ -4013,7 +4040,7 @@ True if \fIfile1\fP is older than \fIfile2\fP, or if \fIfile2\fP exists and \fIfile1\fP does not. .TP .B \-o \fIoptname\fP -True if shell option +True if the shell option .I optname is enabled. See the list of options under the description of the @@ -4022,6 +4049,11 @@ option to the .B set builtin below. .TP +.B \-v \fIvarname\fP +True if the shell variable +.I varname +is set (has been assigned a value). +.TP .B \-z \fIstring\fP True if the length of \fIstring\fP is zero. .TP @@ -7050,10 +7082,10 @@ is greater than the number of enclosing loops, the last enclosing loop (the ``top-level'' loop) is resumed. The return value is 0 unless \fIn\fP is not greater than or equal to 1. .TP -\fBdeclare\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBdeclare\fP [\fB\-aAfFgilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD 0 .TP -\fBtypeset\fP [\fB\-aAfFilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] +\fBtypeset\fP [\fB\-aAfFgilrtux\fP] [\fB\-p\fP] [\fIname\fP[=\fIvalue\fP] ...] .PD Declare variables and/or give them attributes. If no \fIname\fPs are given then display the values of variables. @@ -7082,6 +7114,11 @@ are displayed as well. The .B \-F option implies .BR \-f . +The +.B \-g +option forces variables to be created or modified at the global scope, +even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. The following options can be used to restrict output to variables with the specified attribute or to give variables attributes: @@ -7136,11 +7173,11 @@ turns off the attribute instead, with the exceptions that \fB+a\fP may not be used to destroy an array variable and \fB+r\fP will not remove the readonly attribute. -When used in a function, -makes each +When used in a function, makes each \fIname\fP local, as with the .B local -command. +command, +unless the \fB\-g\P option is supplied, If a variable name is followed by =\fIvalue\fP, the value of the variable is set to \fIvalue\fP. The return value is 0 unless an invalid option is encountered, @@ -7293,6 +7330,14 @@ the eight-bit character whose value is the octal value \fInnn\fP .B \ex\fIHH\fP the eight-bit character whose value is the hexadecimal value \fIHH\fP (one or two hex digits) +.TP +.B \eu\fIHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHH\fP (one to four hex digits) +.TP +.B \eU\fIHHHHHHHH\fP +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +\fIHHHHHHHH\fP (one to eight hex digits) .PD .RE .TP @@ -7988,7 +8033,8 @@ is specified without .BR \-c , the default quantum is 5000. When \fIcallback\fP is evaluated, it is supplied the index of the next -array element to be assigned as an additional argument. +array element to be assigned and the line to be assigned to that element +as additional arguments. \fIcallback\fP is evaluated after the line is read but before the array element is assigned. .PP @@ -8052,32 +8098,49 @@ directory change fails. \fBprintf\fP [\fB\-v\fP \fIvar\fP] \fIformat\fP [\fIarguments\fP] Write the formatted \fIarguments\fP to the standard output under the control of the \fIformat\fP. +The \fB\-v\fP option causes the output to be assigned to the variable +\fIvar\fP rather than being printed to the standard output. +.sp 1 The \fIformat\fP 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 \fIargument\fP. -In addition to the standard \fIprintf\fP(1) formats, \fB%b\fP causes +In addition to the standard \fIprintf\fP(1) format specifications, +\fBprintf\fP interprets the following extensions: +.RS +.PD 0 +.TP +.B %b +causes \fBprintf\fP to expand backslash escape sequences in the corresponding \fIargument\fP (except that \fB\ec\fP terminates output, backslashes in \fB\e\(aq\fP, \fB\e"\fP, and \fB\e?\fP are not removed, and octal escapes -beginning with \fB\e0\fP may contain up to four digits), -and \fB%q\fP causes \fBprintf\fP to output the corresponding +beginning with \fB\e0\fP may contain up to four digits). +.TP +.B %q +causes \fBprintf\fP to output the corresponding \fIargument\fP in a format that can be reused as shell input. -.sp 1 +.TP +.B %(\fIdatefmt\fP)T +causes \fBprintf\fP to output the date-time string resulting from using +\fIdatefmt\fP as a format string for \fIstrftime\fP(3). The corresponding +\fIargument\fP is an integer representing the number of seconds since the +epoch. Two special argument values may be used: -1 represents the current +time, and -2 represents the time the shell was invoked. +.PD +.PP Arguments to non-string format specifiers are treated as C constants, except that a leading plus or minus sign is allowed, and if the leading character is a single or double quote, the value is the ASCII value of the following character. -.sp 1 -The \fB\-v\fP option causes the output to be assigned to the variable -\fIvar\fP rather than being printed to the standard output. -.sp 1 +.PP The \fIformat\fP is reused as necessary to consume all of the \fIarguments\fP. If the \fIformat\fP requires more \fIarguments\fP 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. +appropriate, had been supplied. +The return value is zero on success, non-zero on failure. +.RE .TP \fBpushd\fP [\fB\-n\fP] [+\fIn\fP] [\-\fIn\fP] .PD 0 diff --git a/doc/bashref.texi b/doc/bashref.texi index d9f36fa0..be78c6ec 100644 --- a/doc/bashref.texi +++ b/doc/bashref.texi @@ -596,6 +596,7 @@ some other grouping. * Lists:: How to execute commands sequentially. * Compound Commands:: Shell commands for control flow. * Coprocesses:: Two-way communication between commands. +* GNU Parallel:: Running commands in parallel. @end menu @node Simple Commands @@ -654,6 +655,12 @@ The use of @code{time} as a reserved word permits the timing of shell builtins, shell functions, and pipelines. An external @code{time} command cannot time these easily. +When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time} +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The @env{TIMEFORMAT} variable may be used to specify the format of +the time information. + If the pipeline is not executed asynchronously (@pxref{Lists}), the shell waits for all commands in the pipeline to complete. @@ -1132,6 +1139,79 @@ builtin command may be used to wait for the coprocess to terminate. The return status of a coprocess is the exit status of @var{command}. +@node GNU Parallel +@subsection GNU Parallel + +GNU Parallel, as its name suggests, can be used to build and run commands +in parallel. You may run the same command with different arguments, whether +they are filenames, usernames, hostnames, or lines read from files. + +For a complete description, refer to the GNU Parallel documentation. A few +examples should provide a brief introduction to its use. + +For example, it is easy to prefix each line in a text file with a specified +string: +@example +cat file | parallel -k echo prefix_string +@end example + +The @option{-k} option is required to preserve the lines' order. + +Similarly, you can append a specified string to each line in a text file: +@example +cat file | parallel -k echo @{@} append_string +@end example + +You can use Parallel to move files from the current directory when the +number of files is too large to process with one @code{mv} invocation: +@example +ls | parallel mv @{@} destdir +@end example + +As you can see, the @{@} is replaced with each line read from standard input. +This will run as many @code{mv} commands as there are files in the current +directory. You can emulate a parallel @code{xargs} by adding the @option{-X} +option: +@example +ls | parallel -X mv @{@} destdir +@end example + +GNU Parallel can replace certain common idioms that operate on lines read +from a file (in this case, filenames): +@example + for x in $(cat list); do + do-something1 $x config-$x + do-something2 < $x + done | process-output +@end example + +with a more compact syntax reminiscent of lambdas: +@example +cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | process-output +@end example + +Parallel provides a built-in mechanism to remove filename extensions, which +lends itself to batch file transformations or renaming: +@example +ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" +@end example + +This will recompress all files in the current directory with names ending +in .gz using bzip2, running one job per CPU (-j+0) in parallel. + +If a command generates output, you may want to preserve the input order in +the output. For instance, the following command +@example +@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel traceroute +@end example + +will display as output the traceroute invocation that finishes first. Using +the @option{-k} option, as we saw above +@example +@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel -k traceroute +@end example +will ensure that the output of @code{traceroute foss.org.my} is displayed first. + @node Shell Functions @section Shell Functions @cindex shell function @@ -1204,6 +1284,11 @@ shell option has been enabled. @xref{Bourne Shell Builtins}, for the description of the @code{trap} builtin. +The @env{FUNCNEST} variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. + If the builtin command @code{return} is executed in a function, the function completes and execution resumes with the next command after the function @@ -3456,6 +3541,11 @@ If the @code{extdebug} shell option is enabled using @code{shopt} (@pxref{The Shopt Builtin}), the source file name and line number where the function is defined are displayed as well. @option{-F} implies @option{-f}. + +The @option{-g} option forces variables to be created or modified at +the global scope, even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. + The following options can be used to restrict output to variables with the specified attributes or to give variables attributes: @@ -3504,8 +3594,9 @@ with the exceptions that @samp{+a} may not be used to destroy an array variable and @samp{+r} will not remove the readonly attribute. When used in a function, @code{declare} makes each @var{name} local, -as with the @code{local} command. If a variable name is followed by -=@var{value}, the value of the variable is set to @var{value}. +as with the @code{local} command, unless the @samp{-g} option is used. +If a variable name is followed by =@var{value}, the value of the variable +is set to @var{value}. The return status is zero unless an invalid option is encountered, an attempt is made to define a function using @samp{-f foo=bar}, @@ -3693,7 +3784,8 @@ Specify the number of lines read between each call to @var{callback}. If @option{-C} is specified without @option{-c}, the default quantum is 5000. When @var{callback} is evaluated, it is supplied the index of the next -array element to be assigned as an additional argument. +array element to be assigned and the line to be assigned to that element +as additional arguments. @var{callback} is evaluated after the line is read but before the array element is assigned. @@ -3711,28 +3803,41 @@ printf [-v @var{var}] @var{format} [@var{arguments}] @end example Write the formatted @var{arguments} to the standard output under the control of the @var{format}. +The @option{-v} option causes the output to be assigned to the variable +@var{var} rather than being printed to the standard output. + The @var{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 @var{argument}. -In addition to the standard @code{printf(1)} formats, @samp{%b} causes -@code{printf} to expand backslash escape sequences in the corresponding -@var{argument}, +In addition to the standard @code{printf(1)} formats, @code{printf} +interprets the following extensions: + +@table @code +@item %b +causes @code{printf} to expand backslash escape sequences in the +corresponding @var{argument}, (except that @samp{\c} terminates output, backslashes in @samp{\'}, @samp{\"}, and @samp{\?} are not removed, and octal escapes -beginning with @samp{\0} may contain up to four digits), -and @samp{%q} causes @code{printf} to output the +beginning with @samp{\0} may contain up to four digits). +@item %q +causes @code{printf} to output the corresponding @var{argument} in a format that can be reused as shell input. +@item %(@var{datefmt})T +causes @code{printf} to output the date-time string resulting from using +@var{datefmt} as a format string for @code{strftime}(3). The corresponding +@var{argument} is an integer representing the number of seconds since the +epoch. Two special argument values may be used: -1 represents the current +time, and -2 represents the time the shell was invoked. +@end table +@noindent Arguments to non-string format specifiers are treated as C language constants, except that a leading plus or minus sign is allowed, and if the leading character is a single or double quote, the value is the ASCII value of the following character. -The @option{-v} option causes the output to be assigned to the variable -@var{var} rather than being printed to the standard output. - The @var{format} is reused as necessary to consume all of the @var{arguments}. If the @var{format} requires more @var{arguments} than are supplied, the extra format specifications behave as if a zero value or null string, as @@ -4954,6 +5059,11 @@ Assignments to @env{FUNCNAME} have no effect and return an error status. If @env{FUNCNAME} is unset, it loses its special properties, even if it is subsequently reset. +@item FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. + @item GLOBIGNORE A colon-separated list of patterns defining the set of filenames to be ignored by filename expansion. @@ -5855,10 +5965,13 @@ True if @var{file1} is older than @var{file2}, or if @var{file2} exists and @var{file1} does not. @item -o @var{optname} -True if shell option @var{optname} is enabled. +True if the shell option @var{optname} is enabled. The list of options appears in the description of the @option{-o} option to the @code{set} builtin (@pxref{The Set Builtin}). +@item -v @var{varname} +True if the shell variable @var{varname} is set (has been assigned a value). + @item -z @var{string} True if the length of @var{string} is zero. @@ -6490,6 +6603,11 @@ Non-interactive shells exit if a syntax error in an arithmetic expansion results in an invalid expression. @item +Non-interactive shells exit if there is a syntax error in a script read +with the @code{.} or @code{source} builtins, or in a string processed by +the @code{eval} builtin. + +@item Redirection operators do not perform filename expansion on the word in the redirection unless the shell is interactive. @@ -6508,6 +6626,19 @@ causes a fatal syntax error in non-interactive shells. during command lookup. @item +The @code{time} reserved word may be used by itself as a command. When +used in this way, it displays timing statistics for the shell and its +completed children. The @env{TIMEFORMAT} variable controls the format +of the timing information. + +@item +When parsing and expanding a $@{@dots{}@} expansion that appears within +double quotes, single quotes are no longer special and cannot be used to +quote a closing brace or other special character, unless the operator is +one of those defined to perform pattern removal. In this case, they do +not have to appear as matched pairs. + +@item If a @sc{posix} special builtin returns an error status, a non-interactive shell exits. The fatal errors are those listed in the @sc{posix} standard, and include things like passing incorrect options, diff --git a/doc/bashref.texi~ b/doc/bashref.texi~ index 15ede23b..9cb2e6b4 100644 --- a/doc/bashref.texi~ +++ b/doc/bashref.texi~ @@ -522,6 +522,12 @@ the eight-bit character whose value is the octal value @var{nnn} @item \x@var{HH} the eight-bit character whose value is the hexadecimal value @var{HH} (one or two hex digits) +@item \u@var{HHHH} +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +@var{HHHH} (one to four hex digits) +@item \U@var{HHHHHHHH} +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +@var{HHHHHHHH} (one to eight hex digits) @item \c@var{x} a control-@var{x} character @end table @@ -590,6 +596,7 @@ some other grouping. * Lists:: How to execute commands sequentially. * Compound Commands:: Shell commands for control flow. * Coprocesses:: Two-way communication between commands. +* GNU Parallel:: Running commands in parallel. @end menu @node Simple Commands @@ -648,6 +655,12 @@ The use of @code{time} as a reserved word permits the timing of shell builtins, shell functions, and pipelines. An external @code{time} command cannot time these easily. +When the shell is in @sc{posix} mode (@pxref{Bash POSIX Mode}), @code{time} +may be followed by a newline. In this case, the shell displays the +total user and system time consumed by the shell and its children. +The @env{TIMEFORMAT} variable may be used to specify the format of +the time information. + If the pipeline is not executed asynchronously (@pxref{Lists}), the shell waits for all commands in the pipeline to complete. @@ -1126,6 +1139,79 @@ builtin command may be used to wait for the coprocess to terminate. The return status of a coprocess is the exit status of @var{command}. +@node GNU Parallel +@subsection GNU Parallel + +GNU Parallel, as its name suggests, can be used to build and run commands +in parallel. You may run the same command with different arguments, whether +they are filenames, usernames, hostnames, or lines read from files. + +For a complete description, refer to the GNU Parallel documentation. A few +examples should provide a brief introduction to its use. + +For example, it is easy to prefix each line in a text file with a specified +string: +@example +cat file | parallel -k echo prefix_string +@end example + +The @option{-k} option is required to preserve the lines' order. + +Similarly, you can append a specified string to each line in a text file: +@example +cat file | parallel -k echo @{@} append_string +@end example + +You can use Parallel to move files from the current directory when the +number of files is too large to process with one @code{mv} invocation: +@example +ls | parallel mv @{@} destdir +@end example + +As you can see, the @{@} is replaced with each line read from standard input. +This will run as many @code{mv} commands as there are files in the current +directory. You can emulate a parallel @code{xargs} by adding the @option{-X} +option: +@example +ls | parallel -X mv @{@} destdir +@end example + +GNU Parallel can replace certain common idioms that operate on lines read +from a file (in this case, filenames): +@example + for x in $(cat list); do + do-something1 $x config-$x + do-something2 < $x + done | process-output +@end example + +with a more compact syntax reminiscent of lambdas: +@example +cat list | parallel "do-something1 @{@} config-@{@} ; do-something2 < @{@}" | process-output +@end example + +Parallel provides a built-in mechanism to remove filename extensions, which +lends itself to batch file transformations or renaming: +@example +ls *.gz | parallel -j+0 "zcat @{@} | bzip2 >@{.@}.bz2 && rm @{@}" +@end example + +This will recompress all files in the current directory with names ending +in .gz using bzip2, running one job per CPU (-j+0) in parallel. + +If a command generates output, you may want to preserve the input order in +the output. For instance, the following command +@example +@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel traceroute +@end example + +will display as output the traceroute invocation that finishes first. Using +the @option{-k} option, as we saw above +@example +@{ echo foss.org.my ; echo debian.org; echo freenetproject.org; @} | parallel -k traceroute +@end example +will ensure that the output of @code{traceroute foss.org.my} is displayed first. + @node Shell Functions @section Shell Functions @cindex shell function @@ -1198,6 +1284,11 @@ shell option has been enabled. @xref{Bourne Shell Builtins}, for the description of the @code{trap} builtin. +The @env{FUNCNEST} variable, if set to a numeric value greater +than 0, defines a maximum function nesting level. Function +invocations that exceed the limit cause the entire command to +abort. + If the builtin command @code{return} is executed in a function, the function completes and execution resumes with the next command after the function @@ -3450,6 +3541,11 @@ If the @code{extdebug} shell option is enabled using @code{shopt} (@pxref{The Shopt Builtin}), the source file name and line number where the function is defined are displayed as well. @option{-F} implies @option{-f}. + +The @option{-g} option forces variables to be created or modified at +the global scope, even when \fBdeclare\fP is executed in a shell function. +It is ignored in all other cases. + The following options can be used to restrict output to variables with the specified attributes or to give variables attributes: @@ -3498,8 +3594,9 @@ with the exceptions that @samp{+a} may not be used to destroy an array variable and @samp{+r} will not remove the readonly attribute. When used in a function, @code{declare} makes each @var{name} local, -as with the @code{local} command. If a variable name is followed by -=@var{value}, the value of the variable is set to @var{value}. +as with the @code{local} command, unless the @samp{-g} option is used. +If a variable name is followed by =@var{value}, the value of the variable +is set to @var{value}. The return status is zero unless an invalid option is encountered, an attempt is made to define a function using @samp{-f foo=bar}, @@ -3557,6 +3654,12 @@ the eight-bit character whose value is the octal value @var{nnn} @item \x@var{HH} the eight-bit character whose value is the hexadecimal value @var{HH} (one or two hex digits) +@item \u@var{HHHH} +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +@var{HHHH} (one to four hex digits) +@item \U@var{HHHHHHHH} +the Unicode (ISO/IEC 10646) character whose value is the hexadecimal value +@var{HHHHHHHH} (one to eight hex digits) @end table @item enable @@ -3681,7 +3784,8 @@ Specify the number of lines read between each call to @var{callback}. If @option{-C} is specified without @option{-c}, the default quantum is 5000. When @var{callback} is evaluated, it is supplied the index of the next -array element to be assigned as an additional argument. +array element to be assigned and the line to be assigned to that element +as additional arguments. @var{callback} is evaluated after the line is read but before the array element is assigned. @@ -4942,6 +5046,11 @@ Assignments to @env{FUNCNAME} have no effect and return an error status. If @env{FUNCNAME} is unset, it loses its special properties, even if it is subsequently reset. +@item FUNCNEST +If set to a numeric value greater than 0, defines a maximum function +nesting level. Function invocations that exceed this nesting level +will cause the current command to abort. + @item GLOBIGNORE A colon-separated list of patterns defining the set of filenames to be ignored by filename expansion. @@ -5843,10 +5952,13 @@ True if @var{file1} is older than @var{file2}, or if @var{file2} exists and @var{file1} does not. @item -o @var{optname} -True if shell option @var{optname} is enabled. +True if the shell option @var{optname} is enabled. The list of options appears in the description of the @option{-o} option to the @code{set} builtin (@pxref{The Set Builtin}). +@item -v @var{varname} +True if the shell variable @var{varname} is set (has been assigned a value). + @item -z @var{string} True if the length of @var{string} is zero. @@ -6478,6 +6590,11 @@ Non-interactive shells exit if a syntax error in an arithmetic expansion results in an invalid expression. @item +Non-interactive shells exit if there is a syntax error in a script read +with the @code{.} or @code{source} builtins, or in a string processed by +the @code{eval} builtin. + +@item Redirection operators do not perform filename expansion on the word in the redirection unless the shell is interactive. @@ -6496,6 +6613,19 @@ causes a fatal syntax error in non-interactive shells. during command lookup. @item +The @code{time} reserved word may be used by itself as a command. When +used in this way, it displays timing statistics for the shell and its +completed children. The @env{TIMEFORMAT} variable controls the format +of the timing information. + +@item +When parsing and expanding a $@{@dots{}@} expansion that appears within +double quotes, single quotes are no longer special and cannot be used to +quote a closing brace or other special character, unless the operator is +one of those defined to perform pattern removal. In this case, they do +not have to appear as matched pairs. + +@item If a @sc{posix} special builtin returns an error status, a non-interactive shell exits. The fatal errors are those listed in the @sc{posix} standard, and include things like passing incorrect options, diff --git a/doc/version.texi b/doc/version.texi index 972af30c..16b3c8ed 100644 --- a/doc/version.texi +++ b/doc/version.texi @@ -2,9 +2,9 @@ Copyright (C) 1988-2010 Free Software Foundation, Inc. @end ignore -@set LASTCHANGE Sat Apr 17 23:23:55 EDT 2010 +@set LASTCHANGE Sun May 30 17:03:21 EDT 2010 @set EDITION 4.1 @set VERSION 4.1 -@set UPDATED 17 April 2010 -@set UPDATED-MONTH April 2010 +@set UPDATED 30 May 2010 +@set UPDATED-MONTH May 2010 diff --git a/doc/version.texi~ b/doc/version.texi~ index 1628278f..76d40573 100644 --- a/doc/version.texi~ +++ b/doc/version.texi~ @@ -2,9 +2,9 @@ Copyright (C) 1988-2010 Free Software Foundation, Inc. @end ignore -@set LASTCHANGE Fri Jan 15 10:50:20 EST 2010 +@set LASTCHANGE Sat May 29 21:00:00 EDT 2010 @set EDITION 4.1 @set VERSION 4.1 -@set UPDATED 15 January 2010 -@set UPDATED-MONTH January 2010 +@set UPDATED 29 May 2010 +@set UPDATED-MONTH May 2010 |