688 lines
16 KiB
HTML
688 lines
16 KiB
HTML
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
|
|
<HTML><HEAD><TITLE>Man page of XARGS</TITLE>
|
|
</HEAD><BODY>
|
|
<H1>XARGS</H1>
|
|
Section: User Commands (1)<BR><A HREF="#index">Index</A>
|
|
<A HREF="/cgi-bin/man/man2html">Return to Main Contents</A><HR>
|
|
|
|
<A NAME="lbAB"> </A>
|
|
<H2>NAME</H2>
|
|
|
|
xargs - build and execute command lines from standard input
|
|
<A NAME="lbAC"> </A>
|
|
<H2>SYNOPSIS</H2>
|
|
|
|
<B>xargs</B>
|
|
|
|
|
|
[<I>options</I>]
|
|
[<I>command</I> [<I>initial-arguments</I>]]
|
|
|
|
<A NAME="lbAD"> </A>
|
|
<H2>DESCRIPTION</H2>
|
|
|
|
This manual page
|
|
documents the GNU version of
|
|
<B>xargs</B>.
|
|
|
|
<B>xargs</B>
|
|
|
|
reads items from the standard input, delimited by blanks (which can be
|
|
protected with double or single quotes or a backslash) or newlines,
|
|
and executes the
|
|
<I>command</I>
|
|
|
|
(default is
|
|
<I>/bin/echo</I>)
|
|
|
|
one or more times with any
|
|
<I>initial-arguments</I>
|
|
|
|
followed by items read from standard input. Blank lines on the
|
|
standard input are ignored.
|
|
<P>
|
|
|
|
The command line for
|
|
<I>command</I>
|
|
|
|
is built up until it reaches a system-defined limit (unless the
|
|
<B>-n</B>
|
|
|
|
and
|
|
<B>-L</B>
|
|
|
|
options are used). The specified
|
|
<I>command</I>
|
|
|
|
will be invoked as many times as necessary to use up the list of input
|
|
items. In general, there will be many fewer invocations of
|
|
<I>command</I>
|
|
|
|
than there were items in the input. This will normally have
|
|
significant performance benefits. Some commands can usefully be
|
|
executed in parallel too; see the
|
|
<B>-P</B>
|
|
|
|
option.
|
|
<P>
|
|
|
|
Because Unix filenames can contain blanks and newlines, this default
|
|
behaviour is often problematic; filenames containing blanks
|
|
and/or newlines are incorrectly processed by
|
|
<B>xargs</B>.
|
|
|
|
In these situations it is better to use the
|
|
<B>-0</B>
|
|
|
|
option, which
|
|
prevents such problems. When using this option you will need to
|
|
ensure that the program which produces the input for
|
|
<B>xargs</B>
|
|
|
|
also uses a null character as a separator. If that program is
|
|
GNU
|
|
<B>find</B>
|
|
|
|
for example, the
|
|
<B>-print0</B>
|
|
|
|
option does this for you.
|
|
<P>
|
|
|
|
If any invocation of the command exits with a status of 255,
|
|
<B>xargs</B>
|
|
|
|
will stop immediately without reading any further input. An error
|
|
message is issued on stderr when this happens.
|
|
<A NAME="lbAE"> </A>
|
|
<H2>OPTIONS</H2>
|
|
|
|
<DL COMPACT>
|
|
<DT id="1">
|
|
<DD>
|
|
<B>-0, --null</B>
|
|
|
|
Input items are terminated by a null character instead of by
|
|
whitespace, and the quotes and backslash are not special (every
|
|
character is taken literally). Disables the end of file string, which
|
|
is treated like any other argument. Useful when input items might
|
|
contain white space, quote marks, or backslashes. The GNU find
|
|
-print0 option produces input suitable for this mode.
|
|
<P>
|
|
<DT id="2">
|
|
<DD>
|
|
<B>-a </B><I>file</I><B>, --arg-file=</B><I>file</I>
|
|
|
|
Read items from
|
|
<I>file</I>
|
|
|
|
instead of standard input. If you use this option, stdin remains
|
|
unchanged when commands are run. Otherwise, stdin is redirected
|
|
from
|
|
<I>/dev/null</I>.
|
|
|
|
<P>
|
|
<DT id="3">
|
|
<DD>
|
|
<B>--delimiter=</B><I>delim</I><B>, -d</B><I> delim</I>
|
|
|
|
Input items are terminated by the specified character. The specified
|
|
delimiter may be a single character, a C-style character escape such
|
|
as
|
|
<B>\n</B>,
|
|
|
|
or an octal or hexadecimal escape code. Octal and hexadecimal
|
|
escape codes are understood as for the
|
|
<B>printf</B>
|
|
|
|
command. Multibyte characters are not supported.
|
|
When processing the input, quotes and backslash are not special; every
|
|
character in the input is taken literally. The
|
|
<B>-d</B>
|
|
|
|
option disables any end-of-file string, which is treated like any
|
|
other argument. You can use this option when the input consists of
|
|
simply newline-separated items, although it is almost always better to
|
|
design your program to use
|
|
<B>--null</B>
|
|
|
|
where this is possible.
|
|
<P>
|
|
<DT id="4"><B>-E</B><I> eof-str</I>
|
|
|
|
<DD>
|
|
Set the end of file string to <I>eof-str</I>. If the end of file
|
|
string occurs as a line of input, the rest of the input is ignored.
|
|
If neither
|
|
<B>-E</B>
|
|
|
|
nor
|
|
<B>-e</B>
|
|
|
|
is used, no end of file string is used.
|
|
<DT id="5">
|
|
<DD>
|
|
<B>-e</B>[<I>eof-str</I>], <B>--eof</B>[<I>=eof-str</I>]
|
|
|
|
This option is a synonym for the
|
|
<B>-E</B>
|
|
|
|
option. Use
|
|
<B>-E</B>
|
|
|
|
instead,
|
|
because it is POSIX compliant while this option is not. If
|
|
<I>eof-str</I> is omitted, there is no end of file string. If neither
|
|
<B>-E</B>
|
|
|
|
nor
|
|
<B>-e</B>
|
|
|
|
is used, no end of file string is used.
|
|
<DT id="6"><B>-I</B><I> replace-str</I>
|
|
|
|
<DD>
|
|
Replace occurrences of <I>replace-str</I> in the initial-arguments with
|
|
names read from standard input. Also, unquoted blanks do not
|
|
terminate input items; instead the separator is the newline character.
|
|
Implies
|
|
<B>-x</B>
|
|
|
|
and
|
|
<B>-L</B>
|
|
|
|
1.
|
|
<DT id="7">
|
|
<DD>
|
|
<B>-i</B>[<I>replace-str</I>], <B>--replace</B>[<I>=replace-str</I>]
|
|
|
|
This option is a synonym for
|
|
<B>-I</B><I>replace-str</I>
|
|
|
|
if
|
|
<I>replace-str</I>
|
|
|
|
is specified. If the
|
|
<I>replace-str</I>
|
|
|
|
argument is missing, the effect is the same as
|
|
<B>-I</B>{}.
|
|
|
|
This option is deprecated; use
|
|
<B>-I</B>
|
|
|
|
instead.
|
|
<DT id="8"><B>-L</B><I> max-lines</I>
|
|
|
|
<DD>
|
|
Use at most <I>max-lines</I> nonblank input lines per command line.
|
|
Trailing blanks cause an input line to be logically continued on the
|
|
next input line. Implies
|
|
<B>-x</B>.
|
|
|
|
<DT id="9">
|
|
<DD>
|
|
<B>-l</B>[<I>max-lines</I>], <B>--max-lines</B>[=<I>max-lines</I>]
|
|
|
|
Synonym for the
|
|
<B>-L</B>
|
|
|
|
option. Unlike
|
|
<B>-L</B>,
|
|
|
|
the
|
|
<I>max-lines</I>
|
|
|
|
argument is optional. If
|
|
<I>max-lines</I>
|
|
|
|
is not specified, it defaults to one. The
|
|
<B>-l</B>
|
|
|
|
option is deprecated since the POSIX standard specifies
|
|
<B>-L</B>
|
|
|
|
instead.
|
|
<DT id="10">
|
|
<DD>
|
|
<B>-n</B><I> max-args</I><B>, </B><I></I><B>--max-args</B><I></I>=<I>max-args</I>
|
|
|
|
Use at most <I>max-args</I> arguments per command line. Fewer than
|
|
<I>max-args</I>
|
|
|
|
arguments will be used if the size (see the
|
|
<B>-s</B>
|
|
|
|
option) is exceeded, unless the
|
|
<B>-x</B>
|
|
|
|
option is given, in which case
|
|
<B>xargs will exit.</B>
|
|
|
|
<DT id="11">
|
|
<DD>
|
|
<B>-P</B><I> max-procs</I>, <I></I><B>--max-procs</B><I></I>=<I>max-procs</I>
|
|
|
|
Run up to
|
|
<I>max-procs</I>
|
|
|
|
processes at a time; the default is 1. If
|
|
<I>max-procs</I>
|
|
|
|
is 0,
|
|
<B>xargs</B>
|
|
|
|
will run as many processes as
|
|
possible at a time. Use the
|
|
<B>-n</B>
|
|
|
|
option or the
|
|
<B>-L</B>
|
|
|
|
option with
|
|
<B>-P</B>;
|
|
|
|
otherwise chances are that only one exec will be done.
|
|
While
|
|
<B>xargs</B>
|
|
|
|
is running, you can send its process a SIGUSR1 signal to increase the
|
|
number of commands to run simultaneously, or a SIGUSR2 to decrease the
|
|
number. You cannot increase it above an implementation-defined limit
|
|
(which is shown with --show-limits). You cannot decrease it below
|
|
1.
|
|
<B>xargs</B>
|
|
|
|
never terminates its commands; when asked to decrease, it merely
|
|
waits for more than one existing command to terminate before starting
|
|
another.
|
|
<P>
|
|
<B>Please note</B>
|
|
|
|
that it is up to the called processes to properly manage parallel
|
|
access to shared resources. For example, if more than one of them
|
|
tries to print to stdout, the output will be produced in an
|
|
indeterminate order (and very likely mixed up) unless the processes
|
|
collaborate in some way to prevent this. Using some kind of locking
|
|
scheme is one way to prevent such problems. In general, using a
|
|
locking scheme will help ensure correct output but reduce performance.
|
|
If you don't want to tolerate the performance difference, simply
|
|
arrange for each process to produce a separate output file (or
|
|
otherwise use separate resources).
|
|
<DT id="12">
|
|
<DD>
|
|
<B>-o, --open-tty</B>
|
|
|
|
Reopen stdin as
|
|
<I>/dev/tty</I>
|
|
|
|
in the child process before executing the command. This is useful if
|
|
you want
|
|
<B>xargs</B>
|
|
|
|
to run an interactive application.
|
|
<DT id="13">
|
|
<DD>
|
|
<B>-p, --interactive</B>
|
|
|
|
Prompt the user about whether to run each command line and read a line
|
|
from the terminal. Only run the command line if the response starts
|
|
with `y' or `Y'. Implies
|
|
<B>-t</B>.
|
|
|
|
<DT id="14">
|
|
<DD>
|
|
<B>--process-slot-var</B>=<I>name</I>
|
|
|
|
Set the environment variable
|
|
<I>name</I>
|
|
|
|
to a unique value in each running child process. Values are reused
|
|
once child processes exit. This can be used in a rudimentary load
|
|
distribution scheme, for example.
|
|
<DT id="15">
|
|
<DD>
|
|
<B>-r, --no-run-if-empty</B>
|
|
|
|
If the standard input does not contain any nonblanks, do not run the
|
|
command. Normally, the command is run once even if there is no input.
|
|
This option is a GNU extension.
|
|
<DT id="16">
|
|
<DD>
|
|
<B>-s</B><I> max-chars</I>, <I></I><B>--max-chars</B><I>=max-chars</I>
|
|
|
|
Use at most <I>max-chars</I> characters per command line, including the
|
|
command and initial-arguments and the terminating nulls at the ends of
|
|
the argument strings. The largest allowed value is system-dependent,
|
|
and is calculated as the argument length limit for exec, less the size
|
|
of your environment, less 2048 bytes of headroom. If this value is
|
|
more than 128KiB, 128Kib is used as the default value; otherwise, the
|
|
default value is the maximum. 1KiB is 1024 bytes.
|
|
<B>xargs</B>
|
|
|
|
automatically adapts to tighter constraints.
|
|
<DT id="17"><B>--show\-limits</B>
|
|
|
|
<DD>
|
|
Display the limits on the command-line length which are imposed by the
|
|
operating system,
|
|
<B>xargs</B>'
|
|
|
|
choice of buffer size and the
|
|
<B>-s</B>
|
|
|
|
option. Pipe the input from
|
|
<I>/dev/null</I>
|
|
|
|
(and perhaps specify
|
|
<B>--no-run-if-empty</B>)
|
|
|
|
if you don't want
|
|
<B>xargs</B>
|
|
|
|
to do anything.
|
|
<DT id="18"><B>-t, --verbose</B>
|
|
|
|
<DD>
|
|
Print the command line on the standard error output before executing
|
|
it.
|
|
<DT id="19">
|
|
<DD>
|
|
<B>-x, --exit</B>
|
|
|
|
Exit if the size (see the
|
|
<B>-s</B>
|
|
|
|
option) is exceeded.
|
|
<DT id="20"><B>--help</B>
|
|
|
|
<DD>
|
|
Print a summary of the options to
|
|
<B>xargs</B>
|
|
|
|
and exit.
|
|
<DT id="21"><B>--version</B>
|
|
|
|
<DD>
|
|
Print the version number of
|
|
<B>xargs</B>
|
|
|
|
and exit.
|
|
</DL>
|
|
<A NAME="lbAF"> </A>
|
|
<H2>EXAMPLES</H2>
|
|
|
|
<PRE>
|
|
<B>find /tmp -name core -type f -print | xargs /bin/rm -f</B>
|
|
|
|
</PRE>
|
|
|
|
Find files named
|
|
<B>core</B>
|
|
|
|
in or below the directory
|
|
<B>/tmp</B>
|
|
|
|
and delete them. Note that this will work incorrectly if there are
|
|
any filenames containing newlines or spaces.
|
|
<P>
|
|
|
|
<B>find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f</B>
|
|
|
|
<P>
|
|
|
|
Find files named
|
|
<B>core</B>
|
|
|
|
in or below the directory
|
|
<B>/tmp</B>
|
|
|
|
and delete them, processing filenames in such a way that file or
|
|
directory names containing spaces or newlines are correctly handled.
|
|
<P>
|
|
<P>
|
|
|
|
<B>find /tmp -depth -name core -type f -delete</B>
|
|
|
|
<P>
|
|
|
|
Find files named
|
|
<B>core</B>
|
|
|
|
in or below the directory
|
|
<B>/tmp</B>
|
|
|
|
and delete them, but more efficiently than in the previous example
|
|
(because we avoid the need to use
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fork">fork</A></B>(2)
|
|
|
|
and
|
|
<B><A HREF="/cgi-bin/man/man2html?2+exec">exec</A></B>(2)
|
|
|
|
to launch
|
|
<B>rm</B>
|
|
|
|
and we don't need the extra
|
|
<B>xargs</B>
|
|
|
|
process).
|
|
<P>
|
|
<P>
|
|
|
|
<PRE>
|
|
<B>cut -d: -f1 < /etc/passwd | sort | xargs echo</B>
|
|
|
|
</PRE>
|
|
|
|
Generates a compact listing of all the users on the system.
|
|
<P>
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAG"> </A>
|
|
<H2>EXIT STATUS</H2>
|
|
|
|
<B>xargs</B>
|
|
|
|
exits with the following status:
|
|
<PRE>
|
|
0 if it succeeds
|
|
123 if any invocation of the command exited with status 1-125
|
|
124 if the command exited with status 255
|
|
125 if the command is killed by a signal
|
|
126 if the command cannot be run
|
|
127 if the command is not found
|
|
1 if some other error occurred.
|
|
</PRE>
|
|
|
|
<P>
|
|
|
|
Exit codes greater than 128 are used by the shell to indicate that
|
|
a program died due to a fatal signal.
|
|
<A NAME="lbAH"> </A>
|
|
<H2>STANDARDS CONFORMANCE</H2>
|
|
|
|
As of GNU xargs version 4.2.9, the default behaviour of
|
|
<B>xargs</B>
|
|
|
|
is not to have a logical end-of-file marker. POSIX (IEEE Std 1003.1,
|
|
2004 Edition) allows this.
|
|
<P>
|
|
|
|
The -l and -i options appear in the 1997 version of the POSIX
|
|
standard, but do not appear in the 2004 version of the standard.
|
|
Therefore you should use -L and -I instead, respectively.
|
|
<P>
|
|
|
|
The -o option is an extension to the POSIX standard for better
|
|
compatibility with BSD.
|
|
<P>
|
|
|
|
The POSIX standard allows implementations to have a limit on the size
|
|
of arguments to the
|
|
<B>exec</B>
|
|
|
|
functions. This limit could be as low as 4096 bytes including the size of the
|
|
environment. For scripts to be portable, they must not rely on a
|
|
larger value. However, I know of no implementation whose actual limit
|
|
is that small. The
|
|
<B>--show-limits</B>
|
|
|
|
option can be used to discover the actual limits in force on the
|
|
current system.
|
|
<P>
|
|
<P>
|
|
<A NAME="lbAI"> </A>
|
|
<H2>SEE ALSO</H2>
|
|
|
|
<B><A HREF="/cgi-bin/man/man2html?1+find">find</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?1+locate">locate</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?5+locatedb">locatedb</A></B>(5), <B><A HREF="/cgi-bin/man/man2html?1+updatedb">updatedb</A></B>(1),
|
|
<B><A HREF="/cgi-bin/man/man2html?2+fork">fork</A></B>(2), <B><A HREF="/cgi-bin/man/man2html?3+execvp">execvp</A></B>(3),
|
|
<B><A HREF="/cgi-bin/man/man2html?1+kill">kill</A></B>(1), <B><A HREF="/cgi-bin/man/man2html?7+signal">signal</A></B>(7),
|
|
<P>
|
|
The full documentation for
|
|
<B>xargs</B>
|
|
|
|
is maintained as a Texinfo manual. If the
|
|
<B>info</B>
|
|
|
|
and
|
|
<B>xargs</B>
|
|
|
|
programs are properly installed at your site, the command
|
|
<B>info xargs</B>
|
|
|
|
should give you access to the complete manual.
|
|
<P>
|
|
<A NAME="lbAJ"> </A>
|
|
<H2>COPYRIGHT</H2>
|
|
|
|
Copyright © 1990-2019 Free Software Foundation, Inc.
|
|
License GPLv3+: GNU GPL version 3 or later <<A HREF="https://gnu.org/licenses/gpl.html">https://gnu.org/licenses/gpl.html</A>>.
|
|
<BR>
|
|
|
|
This is free software: you are free to change and redistribute it.
|
|
There is NO WARRANTY, to the extent permitted by law.
|
|
<P>
|
|
<A NAME="lbAK"> </A>
|
|
<H2>BUGS</H2>
|
|
|
|
The
|
|
<B>-L</B>
|
|
|
|
option is incompatible with the
|
|
<B>-I</B>
|
|
|
|
option, but perhaps should not be.
|
|
<P>
|
|
|
|
It is not possible for
|
|
<B>xargs</B>
|
|
|
|
to be used securely, since there will always be a time gap between the
|
|
production of the list of input files and their use in the commands
|
|
that
|
|
<B>xargs</B>
|
|
|
|
issues. If other users have access to the system, they can manipulate
|
|
the filesystem during this time window to force the action of the
|
|
commands
|
|
<B>xargs</B>
|
|
|
|
runs to apply to files that you didn't intend. For a more detailed
|
|
discussion of this and related problems, please refer to the
|
|
``Security Considerations'' chapter in the findutils Texinfo
|
|
documentation. The
|
|
<B>-execdir</B>
|
|
|
|
option of
|
|
<B>find</B>
|
|
|
|
can often be used as a more secure alternative.
|
|
<P>
|
|
When you use the
|
|
<B>-I</B>
|
|
|
|
option, each line read from the input is buffered
|
|
internally. This means that there is an upper limit on the length
|
|
of input line that
|
|
<B>xargs</B>
|
|
|
|
will accept when used with the
|
|
<B>-I</B>
|
|
|
|
option. To work around this
|
|
limitation, you can use the
|
|
<B>-s</B>
|
|
|
|
option to increase the amount of
|
|
buffer space that
|
|
<B>xargs</B>
|
|
|
|
uses, and you can also use an extra invocation of
|
|
<B>xargs</B>
|
|
|
|
to ensure that very long lines do not occur.
|
|
For example:
|
|
<P>
|
|
|
|
<B>somecommand | xargs -s 50000 echo | xargs -I '{}' -s 100000 rm '{}'</B>
|
|
|
|
<P>
|
|
|
|
Here, the first invocation of
|
|
<B>xargs</B>
|
|
|
|
has no input line length limit
|
|
because it doesn't use the
|
|
<B>-i</B>
|
|
|
|
option. The second invocation of
|
|
<B>xargs</B>
|
|
|
|
does have such a limit, but we have ensured that the it never encounters
|
|
a line which is longer than it can handle. This is not an ideal
|
|
solution. Instead, the
|
|
<B>-i</B>
|
|
|
|
option should not impose a line length
|
|
limit, which is why this discussion appears in the BUGS section.
|
|
The problem doesn't occur with the output of
|
|
<B><A HREF="/cgi-bin/man/man2html?1+find">find</A></B>(1)
|
|
|
|
because it emits just one filename per line.
|
|
<P>
|
|
|
|
The best way to report a bug is to use the form at
|
|
<A HREF="https://savannah.gnu.org/bugs/?group=findutils.">https://savannah.gnu.org/bugs/?group=findutils.</A>
|
|
The reason for this is that you will then be able to track progress in
|
|
fixing the problem. Other comments about <B><A HREF="/cgi-bin/man/man2html?1+xargs">xargs</A></B>(1) and about
|
|
the findutils package in general can be sent to the
|
|
<I>bug-findutils</I>
|
|
|
|
mailing list. To join the list, send email to
|
|
<I><A HREF="mailto:bug-findutils-request@gnu.org">bug-findutils-request@gnu.org</A></I>.
|
|
|
|
<P>
|
|
|
|
<HR>
|
|
<A NAME="index"> </A><H2>Index</H2>
|
|
<DL>
|
|
<DT id="22"><A HREF="#lbAB">NAME</A><DD>
|
|
<DT id="23"><A HREF="#lbAC">SYNOPSIS</A><DD>
|
|
<DT id="24"><A HREF="#lbAD">DESCRIPTION</A><DD>
|
|
<DT id="25"><A HREF="#lbAE">OPTIONS</A><DD>
|
|
<DT id="26"><A HREF="#lbAF">EXAMPLES</A><DD>
|
|
<DT id="27"><A HREF="#lbAG">EXIT STATUS</A><DD>
|
|
<DT id="28"><A HREF="#lbAH">STANDARDS CONFORMANCE</A><DD>
|
|
<DT id="29"><A HREF="#lbAI">SEE ALSO</A><DD>
|
|
<DT id="30"><A HREF="#lbAJ">COPYRIGHT</A><DD>
|
|
<DT id="31"><A HREF="#lbAK">BUGS</A><DD>
|
|
</DL>
|
|
<HR>
|
|
This document was created by
|
|
<A HREF="/cgi-bin/man/man2html">man2html</A>,
|
|
using the manual pages.<BR>
|
|
Time: 00:05:29 GMT, March 31, 2021
|
|
</BODY>
|
|
</HTML>
|