1XARGS(1)                    General Commands Manual                   XARGS(1)
2
3
4

NAME

6       xargs - build and execute command lines from standard input
7

SYNOPSIS

9       xargs  [-0prtx]  [-E  eof-str] [-e[eof-str]] [--eof[=eof-str]] [--null]
10       [-d delimiter] [--delimiter delimiter]  [-I  replace-str]  [-i[replace-
11       str]]    [--replace[=replace-str]]   [-l[max-lines]]   [-L   max-lines]
12       [--max-lines[=max-lines]] [-n max-args] [--max-args=max-args] [-s  max-
13       chars]  [--max-chars=max-chars]  [-P max-procs] [--max-procs=max-procs]
14       [--process-slot-var=name]    [--interactive]    [--verbose]    [--exit]
15       [--no-run-if-empty]   [--arg-file=file]   [--show-limits]   [--version]
16       [--help] [command [initial-arguments]]
17

DESCRIPTION

19       This manual page documents the GNU version of xargs.  xargs reads items
20       from  the  standard  input, delimited by blanks (which can be protected
21       with double or single quotes or a backslash) or newlines, and  executes
22       the  command (default is /bin/echo) one or more times with any initial-
23       arguments followed by items read from standard input.  Blank  lines  on
24       the standard input are ignored.
25
26       The  command line for command is built up until it reaches a system-de‐
27       fined limit (unless the -n and -L options  are  used).   The  specified
28       command  will  be invoked as many times as necessary to use up the list
29       of input items.  In general, there will be many  fewer  invocations  of
30       command  than  there  were items in the input.  This will normally have
31       significant performance benefits.  Some commands can usefully  be  exe‐
32       cuted in parallel too; see the -P option.
33
34       Because  Unix  filenames  can contain blanks and newlines, this default
35       behaviour is often problematic; filenames containing blanks and/or new‐
36       lines  are  incorrectly  processed by xargs.  In these situations it is
37       better to use the -0 option, which prevents such problems.   When using
38       this option you will need to ensure that the program which produces the
39       input for xargs also uses a null character as  a  separator.   If  that
40       program is GNU find for example, the -print0 option does this for you.
41
42       If any invocation of the command exits with a status of 255, xargs will
43       stop immediately without reading any further input.  An  error  message
44       is issued on stderr when this happens.
45

OPTIONS

47       -0, --null
48              Input  items  are  terminated  by a null character instead of by
49              whitespace, and the quotes and backslash are not special  (every
50              character is taken literally).  Disables the end of file string,
51              which is treated like any other  argument.   Useful  when  input
52              items  might  contain  white space, quote marks, or backslashes.
53              The GNU find -print0 option produces  input  suitable  for  this
54              mode.
55
56
57       -a file, --arg-file=file
58              Read items from file instead of standard input.  If you use this
59              option, stdin remains unchanged when commands are  run.   Other‐
60              wise, stdin is redirected from /dev/null.
61
62
63       --delimiter=delim, -d delim
64              Input  items  are  terminated  by  the specified character.  The
65              specified delimiter may be a single character, a C-style charac‐
66              ter  escape  such as \n, or an octal or hexadecimal escape code.
67              Octal and hexadecimal escape codes are  understood  as  for  the
68              printf  command.   Multibyte characters are not supported.  When
69              processing the input, quotes and backslash are not special;  ev‐
70              ery  character  in  the input is taken literally.  The -d option
71              disables any end-of-file string, which is treated like any other
72              argument.   You  can  use this option when the input consists of
73              simply newline-separated items, although  it  is  almost  always
74              better to design your program to use --null where this is possi‐
75              ble.
76
77
78       -E eof-str
79              Set the end of file string to  eof-str.   If  the  end  of  file
80              string  occurs  as a line of input, the rest of the input is ig‐
81              nored.  If neither -E nor -e is used, no end of file  string  is
82              used.
83
84       -e[eof-str], --eof[=eof-str]
85              This option is a synonym for the -E option.  Use -E instead, be‐
86              cause it is POSIX compliant while this option is not.   If  eof-
87              str  is  omitted, there is no end of file string.  If neither -E
88              nor -e is used, no end of file string is used.
89
90       -I replace-str
91              Replace occurrences of replace-str in the initial-arguments with
92              names  read  from  standard input.  Also, unquoted blanks do not
93              terminate input items; instead  the  separator  is  the  newline
94              character.  Implies -x and -L 1.
95
96       -i[replace-str], --replace[=replace-str]
97              This  option  is  a  synonym for -Ireplace-str if replace-str is
98              specified.  If the replace-str argument is missing,  the  effect
99              is the same as -I{}.  This option is deprecated; use -I instead.
100
101       -L max-lines
102              Use  at  most  max-lines  nonblank input lines per command line.
103              Trailing blanks cause an input line to be logically continued on
104              the next input line.  Implies -x.
105
106       -l[max-lines], --max-lines[=max-lines]
107              Synonym for the -L option.  Unlike -L, the max-lines argument is
108              optional.  If max-lines is not specified, it  defaults  to  one.
109              The  -l  option is deprecated since the POSIX standard specifies
110              -L instead.
111
112       -n max-args, --max-args=max-args
113              Use at most max-args arguments per  command  line.   Fewer  than
114              max-args  arguments will be used if the size (see the -s option)
115              is exceeded, unless the -x option is given, in which case  xargs
116              will exit.
117
118       -P max-procs, --max-procs=max-procs
119              Run  up  to max-procs processes at a time; the default is 1.  If
120              max-procs is 0, xargs will run as many processes as possible  at
121              a  time.   Use the -n option or the -L option with -P; otherwise
122              chances are that only one exec will be  done.   While  xargs  is
123              running,  you  can send its process a SIGUSR1 signal to increase
124              the number of commands to run simultaneously, or  a  SIGUSR2  to
125              decrease  the number.  You cannot increase it above an implemen‐
126              tation-defined limit (which is shown with  --show-limits).   You
127              cannot  decrease  it  below  1.  xargs never terminates its com‐
128              mands; when asked to decrease, it merely waits for more than one
129              existing command to terminate before starting another.
130
131              Please  note  that  it is up to the called processes to properly
132              manage parallel access to shared  resources.   For  example,  if
133              more  than one of them tries to print to stdout, the ouptut will
134              be produced in an indeterminate order (and very likely mixed up)
135              unless  the  processes  collaborate in some way to prevent this.
136              Using some kind of locking scheme is one  way  to  prevent  such
137              problems.   In  general, using a locking scheme will help ensure
138              correct output but reduce performance.  If  you  don't  want  to
139              tolerate  the  performance  difference,  simply arrange for each
140              process to produce a separate output file (or otherwise use sep‐
141              arate resources).
142
143       -p, --interactive
144              Prompt  the user about whether to run each command line and read
145              a line from the terminal.  Only run the command line if the  re‐
146              sponse starts with `y' or `Y'.  Implies -t.
147
148       --process-slot-var=name
149              Set the environment variable name to a unique value in each run‐
150              ning child process.  Values are reused once child processes  ex‐
151              it.  This can be used in a rudimentary load distribution scheme,
152              for example.
153
154       -r, --no-run-if-empty
155              If the standard input does not contain any nonblanks, do not run
156              the command.  Normally, the command is run once even if there is
157              no input.  This option is a GNU extension.
158
159       -s max-chars, --max-chars=max-chars
160              Use at most max-chars characters per command line, including the
161              command  and  initial-arguments and the terminating nulls at the
162              ends of the argument strings.  The largest allowed value is sys‐
163              tem-dependent,  and  is  calculated as the argument length limit
164              for exec, less the size of your environment, less 2048 bytes  of
165              headroom.   If this value is more than 128KiB, 128Kib is used as
166              the default value; otherwise, the default value is the  maximum.
167              1KiB  is 1024 bytes.  xargs automatically adapts to tighter con‐
168              straints.
169
170       --show-limits
171              Display the limits on the command-line length which are  imposed
172              by the operating system, xargs' choice of buffer size and the -s
173              option.  Pipe the input  from  /dev/null  (and  perhaps  specify
174              --no-run-if-empty) if you don't want xargs to do anything.
175
176       -t, --verbose
177              Print  the command line on the standard error output before exe‐
178              cuting it.
179
180       -x, --exit
181              Exit if the size (see the -s option) is exceeded.
182
183       --help Print a summary of the options to xargs and exit.
184
185       --version
186              Print the version number of xargs and exit.
187

EXAMPLES

189       find /tmp -name core -type f -print | xargs /bin/rm -f
190
191       Find files named core in or below the directory /tmp and  delete  them.
192       Note  that  this  will work incorrectly if there are any filenames con‐
193       taining newlines or spaces.
194
195       find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
196
197       Find files named core in or below the directory /tmp and  delete  them,
198       processing  filenames  in  such a way that file or directory names con‐
199       taining spaces or newlines are correctly handled.
200
201
202       find /tmp -depth -name core -type f -delete
203
204       Find files named core in or below the directory /tmp and  delete  them,
205       but more efficiently than in the previous example (because we avoid the
206       need to use fork(2) and exec(2) to launch rm and we don't need the  ex‐
207       tra xargs process).
208
209
210       cut -d: -f1 < /etc/passwd | sort | xargs echo
211
212       Generates a compact listing of all the users on the system.
213
214
215       xargs sh -c 'emacs "$@" < /dev/tty' emacs
216
217       Launches  the  minimum  number of copies of Emacs needed, one after the
218       other, to edit the files listed on xargs' standard input.  This example
219       achieves the same effect as BSD's -o option, but in a more flexible and
220       portable way.
221
222
223
224

EXIT STATUS

226       xargs exits with the following status:
227       0 if it succeeds
228       123 if any invocation of the command exited with status 1-125
229       124 if the command exited with status 255
230       125 if the command is killed by a signal
231       126 if the command cannot be run
232       127 if the command is not found
233       1 if some other error occurred.
234
235       Exit codes greater than 128 are used by the shell to  indicate  that  a
236       program died due to a fatal signal.
237

STANDARDS CONFORMANCE

239       As of GNU xargs version 4.2.9, the default behaviour of xargs is not to
240       have a logical end-of-file marker.  POSIX (IEEE Std 1003.1,  2004  Edi‐
241       tion) allows this.
242
243       The -l and -i options appear in the 1997 version of the POSIX standard,
244       but do not appear in the 2004 version of the standard.   Therefore  you
245       should use -L and -I instead, respectively.
246
247       The  POSIX  standard allows implementations to have a limit on the size
248       of arguments to the exec functions.  This limit could be as low as 4096
249       bytes  including the size of the environment.  For scripts to be porta‐
250       ble, they must not rely on a larger value.  However, I know of  no  im‐
251       plementation  whose  actual limit is that small.  The --show-limits op‐
252       tion can be used to discover the actual limits in force on the  current
253       system.
254
255
256

SEE ALSO

258       find(1),   locate(1),  locatedb(5),  updatedb(1),  fork(2),  execvp(3),
259       kill(1), signal(7),
260
261       The  full documentation for xargs is maintained as  a  Texinfo  manual.
262       If the info and xargs programs are properly installed at your site, the
263       command info xargs should give you access to the complete manual.
264
265

BUGS

267       The -L option is incompatible with the -I option,  but  perhaps  should
268       not be.
269
270       It  is not possible for xargs to be used securely, since there will al‐
271       ways be a time gap between the production of the list  of  input  files
272       and  their  use in the commands that xargs issues.  If other users have
273       access to the system, they can manipulate the  filesystem  during  this
274       time  window to force the action of the commands xargs runs to apply to
275       files that you didn't intend.  For a more detailed discussion  of  this
276       and  related  problems, please refer to the ``Security Considerations''
277       chapter in the findutils Texinfo documentation.  The -execdir option of
278       find can often be used as a more secure alternative.
279
280       When  you  use the -I option, each line read from the input is buffered
281       internally.   This means that there is an upper limit on the length  of
282       input  line  that  xargs  will accept when used with the -I option.  To
283       work around this limitation, you can use the -s option to increase  the
284       amount  of  buffer space that xargs uses, and you can also use an extra
285       invocation of xargs to ensure that very long lines do not  occur.   For
286       example:
287
288       somecommand | xargs -s 50000 echo | xargs -I '{}' -s 100000 rm '{}'
289
290       Here,  the first invocation of xargs has no input line length limit be‐
291       cause it doesn't use the -i option.  The  second  invocation  of  xargs
292       does  have  such a limit, but we have ensured that the it never encoun‐
293       ters a line which is longer than it can handle.   This is not an  ideal
294       solution.   Instead, the -i option should not impose a line length lim‐
295       it, which is why this discussion appears  in  the  BUGS  section.   The
296       problem  doesn't occur with the output of find(1) because it emits just
297       one filename per line.
298
299       The best way to report a bug  is  to  use  the  form  at  http://savan
300       nah.gnu.org/bugs/?group=findutils.   The  reason  for  this is that you
301       will then be able to track progress in fixing the problem.   Other com‐
302       ments  about xargs(1) and about the findutils package in general can be
303       sent to the bug-findutils mailing list.  To join the list,  send  email
304       to bug-findutils-request@gnu.org.
305
306
307
308                                                                      XARGS(1)
Impressum