1XARGS(1) General Commands Manual XARGS(1)
2
6 xargs - build and execute command lines from standard input
7
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 [--interactive] [--verbose] [--exit] [--no-run-if-empty]
15 [--arg-file=file] [--show-limits] [--version] [--help] [command
16 [initial-arguments]]
17
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 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 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 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
47 --arg-file=file
48 -a file
49 Read items from file instead of standard input. If you use this
50 option, stdin remains unchanged when commands are run. Other‐
51 wise, stdin is redirected from /dev/null.
52 --null
54 -0 Input items are terminated by a null character instead of by
55 whitespace, and the quotes and backslash are not special (every
56 character is taken literally). Disables the end of file string,
57 which is treated like any other argument. Useful when input
58 items might contain white space, quote marks, or backslashes.
59 The GNU find -print0 option produces input suitable for this
60 mode.
61 --delimiter=delim
64 -d delim
65 Input items are terminated by the specified character. Quotes
66 and backslash are not special; every character in the input is
67 taken literally. Disables the end-of-file string, which is
68 treated like any other argument. This can be used when the in‐
69 put consists of simply newline-separated items, although it is
70 almost always better to design your program to use --null where
71 this is possible. The specified delimiter may be a single char‐
72 acter, a C-style character escape such as \n, or an octal or
73 hexadecimal escape code. Octal and hexadecimal escape codes are
74 understood as for the printf command. Multibyte characters are
75 not supported.
76 -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 --eof[=eof-str]
85 -e[eof-str]
86 This option is a synonym for the -E option. Use -E instead, be‐
87 cause it is POSIX compliant while this option is not. If eof-
88 str is omitted, there is no end of file string. If neither -E
89 nor -e is used, no end of file string is used.
90 --help Print a summary of the options to xargs and exit.
92 -I replace-str
94 Replace occurrences of replace-str in the initial-arguments with
95 names read from standard input. Also, unquoted blanks do not
96 terminate input items; instead the separator is the newline
97 character. Implies -x and -L 1.
98 --replace[=replace-str]
100 -i[replace-str]
101 This option is a synonym for -Ireplace-str if replace-str is
102 specified. If the replace-str argument is missing, the effect
103 is the same as -I{}. This option is deprecated; use -I instead.
104 -L max-lines
106 Use at most max-lines nonblank input lines per command line.
107 Trailing blanks cause an input line to be logically continued on
108 the next input line. Implies -x.
109 --max-lines[=max-lines]
111 -l[max-lines]
112 Synonym for the -L option. Unlike -L, the max-lines argument is
113 optional. If max-lines is not specified, it defaults to one.
114 The -l option is deprecated since the POSIX standard specifies
115 -L instead.
116 --max-args=max-args
118 -n max-args
119 Use at most max-args arguments per command line. Fewer than
120 max-args arguments will be used if the size (see the -s option)
121 is exceeded, unless the -x option is given, in which case xargs
122 will exit.
123 --interactive
125 -p Prompt the user about whether to run each command line and read
126 a line from the terminal. Only run the command line if the re‐
127 sponse starts with `y' or `Y'. Implies -t.
128 --no-run-if-empty
130 -r If the standard input does not contain any nonblanks, do not run
131 the command. Normally, the command is run once even if there is
132 no input. This option is a GNU extension.
133 --max-chars=max-chars
135 -s max-chars
136 Use at most max-chars characters per command line, including the
137 command and initial-arguments and the terminating nulls at the
138 ends of the argument strings. The largest allowed value is sys‐
139 tem-dependent, and is calculated as the argument length limit
140 for exec, less the size of your environment, less 2048 bytes of
141 headroom. If this value is more than 128KiB, 128Kib is used as
142 the default value; otherwise, the default value is the maximum.
143 1KiB is 1024 bytes. xargs automatically adapts to tighter con‐
144 straints.
145 --verbose
147 -t Print the command line on the standard error output before exe‐
148 cuting it.
149 --version
151 Print the version number of xargs and exit.
152 --show-limits
154 Display the limits on the command-line length which are imposed
155 by the operating system, xargs' choice of buffer size and the -s
156 option. Pipe the input from /dev/null (and perhaps specify
157 --no-run-if-empty) if you don't want xargs to do anything.
158 --exit
160 -x Exit if the size (see the -s option) is exceeded.
161 --max-procs=max-procs
163 -P max-procs
164 Run up to max-procs processes at a time; the default is 1. If
165 max-procs is 0, xargs will run as many processes as possible at
166 a time. Use the -n option or the -L option with -P; otherwise
167 chances are that only one exec will be done.
168
170 find /tmp -name core -type f -print | xargs /bin/rm -f
171 Find files named core in or below the directory /tmp and delete them.
173 Note that this will work incorrectly if there are any filenames con‐
174 taining newlines or spaces.
175 find /tmp -name core -type f -print0 | xargs -0 /bin/rm -f
177 Find files named core in or below the directory /tmp and delete them,
179 processing filenames in such a way that file or directory names con‐
180 taining spaces or newlines are correctly handled.
181 find /tmp -depth -name core -type f -delete
184 Find files named core in or below the directory /tmp and delete them,
186 but more efficiently than in the previous example (because we avoid the
187 need to use fork(2) and exec(2) to launch rm and we don't need the ex‐
188 tra xargs process).
189 cut -d: -f1 < /etc/passwd | sort | xargs echo
192 Generates a compact listing of all the users on the system.
194 xargs sh -c 'emacs "$@" < /dev/tty' emacs
197 Launches the minimum number of copies of Emacs needed, one after the
199 other, to edit the files listed on xargs' standard input. This example
200 achieves the same effect as BSD's -o option, but in a more flexible and
201 portable way.
202
207 xargs exits with the following status:
208 0 if it succeeds
209 123 if any invocation of the command exited with status 1-125
210 124 if the command exited with status 255
211 125 if the command is killed by a signal
212 126 if the command cannot be run
213 127 if the command is not found
214 1 if some other error occurred.
215 Exit codes greater than 128 are used by the shell to indicate that a
217 program died due to a fatal signal.
218
220 As of GNU xargs version 4.2.9, the default behaviour of xargs is not to
221 have a logical end-of-file marker. POSIX (IEEE Std 1003.1, 2004 Edi‐
222 tion) allows this.
223 The -l and -i options appear in the 1997 version of the POSIX standard,
225 but do not appear in the 2004 version of the standard. Therefore you
226 should use -L and -I instead, respectively.
227 The POSIX standard allows implementations to have a limit on the size
229 of arguments to the exec functions. This limit could be as low as 4096
230 bytes including the size of the environment. For scripts to be porta‐
231 ble, they must not rely on a larger value. However, I know of no im‐
232 plementation whose actual limit is that small. The --show-limits op‐
233 tion can be used to discover the actual limits in force on the current
234 system.
235
239 find(1), locate(1), locatedb(5), updatedb(1), fork(2), execvp(3), Find‐
240 ing Files (on-line in Info, or printed)
241
243 The -L option is incompatible with the -I option, but perhaps should
244 not be.
245 It is not possible for xargs to be used securely, since there will al‐
247 ways be a time gap between the production of the list of input files
248 and their use in the commands that xargs issues. If other users have
249 access to the system, they can manipulate the filesystem during this
250 time window to force the action of the commands xargs runs to apply to
251 files that you didn't intend. For a more detailed discussion of this
252 and related problems, please refer to the ``Security Considerations''
253 chapter in the findutils Texinfo documentation. The -execdir option of
254 find can often be used as a more secure alternative.
255 When you use the -I option, each line read from the input is buffered
257 internally. This means that there is an upper limit on the length of
258 input line that xargs will accept when used with the -I option. To
259 work around this limitation, you can use the -s option to increase the
260 amount of buffer space that xargs uses, and you can also use an extra
261 invocation of xargs to ensure that very long lines do not occur. For
262 example:
263 somecommand | xargs -s 50000 echo | xargs -I '{}' -s 100000 rm '{}'
265 Here, the first invocation of xargs has no input line length limit be‐
267 cause it doesn't use the -i option. The second invocation of xargs
268 does have such a limit, but we have ensured that the it never encoun‐
269 ters a line which is longer than it can handle. This is not an ideal
270 solution. Instead, the -i option should not impose a line length lim‐
271 it, which is why this discussion appears in the BUGS section. The
272 problem doesn't occur with the output of find(1) because it emits just
273 one filename per line.
274 The best way to report a bug is to use the form at http://savan‐
276 nah.gnu.org/bugs/?group=findutils. The reason for this is that you
277 will then be able to track progress in fixing the problem. Other com‐
278 ments about xargs(1) and about the findutils package in general can be
279 sent to the bug-findutils mailing list. To join the list, send email
280 to bug-findutils-request@gnu.org.
281 XARGS(1)