mirror of
https://https.git.savannah.gnu.org/git/bash.git
synced 2026-07-16 16:36:03 +02:00
commit bash-20100525 snapshot
This commit is contained in:
Chet Ramey
+66
-19
@@ -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
|
||||
|
||||
+82
-19
@@ -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
|
||||
|
||||
+143
-12
@@ -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.
|
||||
|
||||
@@ -6489,6 +6602,11 @@ is not found.
|
||||
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.
|
||||
@@ -6507,6 +6625,19 @@ causes a fatal syntax error in non-interactive shells.
|
||||
@sc{posix} special builtins are found before shell functions
|
||||
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
|
||||
|
||||
+134
-4
@@ -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.
|
||||
|
||||
@@ -6477,6 +6589,11 @@ is not found.
|
||||
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.
|
||||
@@ -6495,6 +6612,19 @@ causes a fatal syntax error in non-interactive shells.
|
||||
@sc{posix} special builtins are found before shell functions
|
||||
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
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
+3
-3
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user