1 .\" Copyright (c) 1990, 1991, 1993
2 .\" The Regents of the University of California. All rights reserved.
4 .\" This code is derived from software contributed to Berkeley by
5 .\" John B. Roll Jr. and the Institute of Electrical and Electronics
8 .\" Redistribution and use in source and binary forms, with or without
9 .\" modification, are permitted provided that the following conditions
11 .\" 1. Redistributions of source code must retain the above copyright
12 .\" notice, this list of conditions and the following disclaimer.
13 .\" 2. Redistributions in binary form must reproduce the above copyright
14 .\" notice, this list of conditions and the following disclaimer in the
15 .\" documentation and/or other materials provided with the distribution.
16 .\" 3. Neither the name of the University nor the names of its contributors
17 .\" may be used to endorse or promote products derived from this software
18 .\" without specific prior written permission.
20 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
21 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
22 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
23 .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
24 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
25 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
26 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
27 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
28 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
29 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
32 .\" @(#)xargs.1 8.1 (Berkeley) 6/6/93
34 .\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
36 .Dd September 21, 2020
41 .Nd "construct argument list(s) and execute utility"
48 .Op Fl R Ar replacements
59 .Op Ar utility Op Ar argument ...
63 utility reads space, tab, newline and end-of-file delimited strings
64 from the standard input and executes
69 Any arguments specified on the command line are given to
71 upon each invocation, followed by some number of the arguments read
72 from the standard input of
74 This is repeated until standard input is exhausted.
76 Spaces, tabs and newlines may be embedded in arguments using single
78 or double (``"'') quotes or backslashes (``\e'').
79 Single quotes escape all non-single quote characters, excluding newlines,
80 up to the matching single quote.
81 Double quotes escape all non-double quote characters, excluding newlines,
82 up to the matching double quote.
83 Any single character, including newlines, may be escaped by a backslash.
85 The options are as follows:
86 .Bl -tag -width indent
92 characters as separators, instead of spaces and newlines.
93 This is expected to be used in concert with the
100 as a logical EOF marker.
104 for each input line, replacing one or more occurrences of
110 flag is specified) arguments to
112 with the entire line of input.
113 The resulting arguments, after replacement is done, will not be allowed to grow
119 bytes; this is implemented by concatenating as much of the argument
122 as possible, to the constructed arguments to
127 The size limit does not apply to arguments to
131 and furthermore, no replacement will be done on
137 If this option is specified,
139 will use the data read from standard input to replace the first occurrence of
141 instead of appending that data after all other arguments.
142 This option will not affect how many arguments will be read from input
144 or the size of the command(s)
148 The option just moves where those arguments will be placed in the command(s)
152 must show up as a distinct
156 It will not be recognized if, for instance, it is in the middle of a
158 Furthermore, only the first occurrence of the
161 For example, the following command will copy the list of files and
162 directories which start with an uppercase letter in the current
166 .Dl /bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir
173 If EOF is reached and fewer lines have been read than
177 will be called with the available lines.
178 .It Fl n Ar number , Fl -max-args= Ns Ar number
179 Set the maximum number of arguments taken from standard input for each
186 standard input arguments if the number of bytes accumulated (see the
188 option) exceeds the specified
190 or there are fewer than
192 arguments remaining for the last invocation of
194 The current default value for
200 in the child process before executing the command.
201 This is useful if you want
203 to run an interactive application.
204 .It Fl P Ar maxprocs , Fl -max-procs= Ns Ar maxprocs
205 Parallel mode: run at most
214 will run as many processes as possible.
215 .It Fl p , Fl -interactive
216 Echo each command to be executed and ask the user whether it should be
218 An affirmative response,
221 causes the command to be executed, any other response causes it to be
223 No commands are executed if the process is not attached to a terminal.
224 .It Fl r , Fl -no-run-if-empty
225 Compatibility with GNU
231 argument at least once, even if
233 input is empty, and it supports a
235 option to inhibit this behavior.
242 argument on empty input, but it supports the
244 option for command-line compatibility with GNU
248 option does nothing in the
252 .It Fl R Ar replacements
253 Specify the maximum number of arguments that
255 will do replacement in.
258 is negative, the number of arguments in which to replace is unbounded.
260 Specify the amount of space (in bytes) that
262 can use for replacements.
266 .It Fl s Ar size , Fl -max-chars= Ns Ar size
267 Set the maximum number of bytes for the command line length provided to
269 The sum of the length of the utility name, the arguments passed to
273 terminators) and the current environment will be less than or equal to
275 The current default value for
280 .It Fl t , Fl -verbose
281 Echo the command to be executed to standard error immediately before it
286 to terminate immediately if a command line containing
288 arguments will not fit in the specified (or default) command line length.
297 Undefined behavior may occur if
299 reads from the standard input.
301 If a command line cannot be assembled, or
302 cannot be invoked, or if an invocation of
304 is terminated by a signal,
307 exits with a value of 255, the
309 utility stops processing input and exits after all invocations of
315 utility exits with a value of 0 if no error occurs.
320 exits with a value of 127, otherwise if
324 exits with a value of 126.
325 If any other error occurs,
327 exits with a value of 1.
329 Create a 3x3 matrix with numbers from 1 to 9.
332 instance receives three lines as arguments:
333 .Bd -literal -offset indent
334 $ seq 1 9 | xargs -L3 echo
340 Duplicate every line from standard input:
341 .Bd -literal -offset indent
342 $ echo -e "one\\ntwo\\nthree" | xargs -I % echo % %
348 Execute at most 2 concurrent instances of
350 every one of them using one of the directories from the standard input:
351 .Bd -literal -offset indent
352 echo -e "/usr/ports\\n/etc\\n/usr/local" | xargs -J % -P2 -n1 find % -name file
361 utility is expected to be
368 options are non-standard
370 extensions which may not be available on other operating systems.
374 utility appeared in PWB UNIX.
378 attempts to invoke another command such that the number of arguments or the
379 size of the environment is increased, it risks
386 utility does not take multibyte characters into account when performing
387 string comparisons for the
391 options, which may lead to incorrect results in some locales.
projects / FreeBSD / FreeBSD.git / blob