xargs/xargs.1

   1 .TH XARGS 1 \" -*- nroff -*-
   2 .SH NAME
   3 xargs \- build and execute command lines from standard input
   4 .SH SYNOPSIS
   5 .B xargs
   6 .nh
   7 [\fB\-0prtx\fR]
   8 [\fB\-E \fIeof-str\fR]
   9 [\fB\-e\fR[\fIeof-str\fR]]
  10 [\fB\-\-eof\fR[=\fIeof-str\fR]]
  11 [\fB\-\-null\fR]
  12 [\fB\-d \fIdelimiter\fR]
  13 [\fB\-\-delimiter \fIdelimiter\fR]
  14 [\fB\-I \fIreplace-str\fR]
  15 [\fB\-i\fR[\fIreplace-str\fR]]
  16 [\fB\-\-replace\fR[=\fIreplace-str\fR]]
  17 [\fB\-l\fR[\fImax-lines\fR]]
  18 [\fB\-L \fImax-lines\fR]
  19 [\fB\-\-max\-lines\fR[=\fImax-lines\fR]]
  20 [\fB\-n \fImax-args\fR]
  21 [\fB\-\-max\-args\fR=\fImax-args\fR]
  22 [\fB\-s \fImax-chars\fR]
  23 [\fB\-\-max\-chars\fR=\fImax-chars\fR]
  24 [\fB\-P \fImax-procs\fR]
  25 [\fB\-\-max\-procs\fR=\fImax-procs\fR]
  26 [\fB\-\-interactive\fR]
  27 [\fB\-\-verbose\fR]
  28 [\fB\-\-exit\fR]
  29 [\fB\-\-no\-run\-if\-empty\fR]
  30 [\fB\-\-arg\-file\fR=\fIfile\fR]
  31 [\fB\-\-show\-limits\fR]
  32 [\fB\-\-version\fR]
  33 [\fB\-\-help\fR]
  34 [\fIcommand\fR [\fIinitial-arguments\fR]]
  35 .hy
  36 .SH DESCRIPTION
  37 This manual page
  38 documents the GNU version of
  39 .BR xargs .
  40 .B xargs
  41 reads items from the standard input, delimited by blanks (which can be
  42 protected with double or single quotes or a backslash) or newlines,
  43 and executes the
  44 .I command
  45 (default is
  46 .IR /bin/echo )
  47 one or more times with any
  48 .I initial-arguments
  49 followed by items read from standard input.  Blank lines on the
  50 standard input are ignored.
  51 .P
  52 Because Unix filenames can contain blanks and newlines, this default
  53 behaviour is often problematic; filenames containing blanks
  54 and/or newlines are incorrectly processed by
  55 .BR xargs .
  56 In these situations it is better to use the
  57 .B \-0
  58 option, which
  59 prevents such problems.   When using this option you will need to
  60 ensure that the program which produces the input for
  61 .B xargs
  62 also uses a null character as a separator.  If that program is
  63 GNU
  64 .B find
  65 for example, the
  66 .B \-print0
  67 option does this for you.
  68 .P
  69 If any invocation of the command exits with a status of 255,
  70 .B xargs
  71 will stop immediately without reading any further input.  An error
  72 message is issued on stderr when this happens.
  73 .SH OPTIONS
  74 .TP
  75 .PD 0
  76 .BI "\-\-arg\-file=" file
  77 .TP
  78 .PD 0
  79 .BI "\-a " file
  80 Read items from
  81 .I file
  82 instead of standard input.  If you use this option, stdin remains
  83 unchanged when commands are run.  Otherwise, stdin is redirected
  84 from
  85 .IR /dev/null .
  86
  87 .TP
  88 .PD 0
  89 .B \-\-null
  90 .TP
  91 .PD
  92 .B \-0
  93 Input items are terminated by a null character instead of by
  94 whitespace, and the quotes and backslash are not special (every
  95 character is taken literally).  Disables the end of file string, which
  96 is treated like any other argument.  Useful when input items might
  97 contain white space, quote marks, or backslashes.  The GNU find
  98 \-print0 option produces input suitable for this mode.
  99
 100 .TP
 101 .PD 0
 102 .BI "\-\-delimiter=" delim
 103 .TP
 104 .PD
 105 .BI \-d " delim"
 106 Input items are terminated by the specified character.  Quotes and
 107 backslash are not special; every character in the input is taken
 108 literally.  Disables the end-of-file string, which is treated like any
 109 other argument.  This can be used when the input consists of simply
 110 newline-separated items, although it is almost always better to design
 111 your program to use
 112 .B \-\-null
 113 where this is possible.  The specified
 114 delimiter may be a single character, a C-style character escape such
 115 as
 116 .BR \en ,
 117 or an octal or hexadecimal escape code.  Octal and hexadecimal
 118 escape codes are understood as for the
 119 .B printf
 120 command.   Multibyte characters are not supported.
 121
 122 .TP
 123 .BI \-E " eof-str"
 124 Set the end of file string to \fIeof-str\fR.  If the end of file
 125 string occurs as a line of input, the rest of the input is ignored.
 126 If neither
 127 .B \-E
 128 nor
 129 .B \-e
 130 is used, no end of file string is used.
 131 .TP
 132 .PD 0
 133 .BR "\-\-eof" [\fI=eof-str\fR]
 134 .TP
 135 .PD
 136 .BR \-e [ \fIeof-str\fR]
 137 This option is a synonym for the
 138 .B \-E
 139 option.  Use
 140 .B \-E
 141 instead,
 142 because it is POSIX compliant while this option is not.  If
 143 \fIeof-str\fR is omitted, there is no end of file string.  If neither
 144 .B \-E
 145 nor
 146 .B \-e
 147 is used, no end of file string is used.
 148 .TP
 149 .B "\-\-help"
 150 Print a summary of the options to
 151 .B xargs
 152 and exit.
 153 .TP
 154 .BI \-I " replace-str"
 155 Replace occurrences of \fIreplace-str\fR in the initial-arguments with
 156 names read from standard input.  Also, unquoted blanks do not
 157 terminate input items; instead the separator is the newline character.
 158 Implies
 159 .B \-x
 160 and
 161 .B \-L
 162 1.
 163 .TP
 164 .PD 0
 165 .BR "\-\-replace" [\fI=replace-str\fR]
 166 .TP
 167 .PD
 168 .BR  \-i "[\fIreplace-str\fR]"
 169 This option is a synonym for
 170 .BI \-I replace-str
 171 if
 172 .I replace-str
 173 is specified, and for
 174 .BR \-I {}
 175 otherwise.  This option is deprecated; use
 176 .B \-I
 177 instead.
 178 .TP
 179 .BI \-L " max-lines"
 180 Use at most \fImax-lines\fR nonblank input lines per command line.
 181 Trailing blanks cause an input line to be logically continued on the
 182 next input line.  Implies
 183 .BR \-x .
 184 .TP
 185 .PD 0
 186 .BR \-\-max-lines "[=\fImax-lines\fR]"
 187 .TP
 188 .PD
 189 .BR \-l "[\fImax-lines\fR]"
 190 Synonym for the
 191 .B \-L
 192 option.  Unlike
 193 .BR \-L ,
 194 the
 195 .I max-lines
 196 argument is optional.  If
 197 .I max-lines
 198 is not specified, it defaults to one.  The
 199 .B \-l
 200 option is deprecated since the POSIX standard specifies
 201 .B \-L
 202 instead.
 203 .TP
 204 .PD 0
 205 .BR "\-\-max\-args" =\fImax-args\fR
 206 .TP
 207 .PD
 208 .BI \-n " max-args"
 209 Use at most \fImax-args\fR arguments per command line.  Fewer than
 210 .I max-args
 211 arguments will be used if the size (see the
 212 .B \-s
 213 option) is exceeded, unless the
 214 .B \-x
 215 option is given, in which case
 216 .B xargs will exit.
 217 .TP
 218 .PD 0
 219 .B \-\-interactive
 220 .TP
 221 .PD
 222 .B \-p
 223 Prompt the user about whether to run each command line and read a line
 224 from the terminal.  Only run the command line if the response starts
 225 with `y' or `Y'.  Implies
 226 .BR -t .
 227 .TP
 228 .PD 0
 229 .B \-\-no\-run\-if\-empty
 230 .TP
 231 .PD
 232 .B \-r
 233 If the standard input does not contain any nonblanks, do not run the
 234 command.  Normally, the command is run once even if there is no input.
 235 This option is a GNU extension.
 236 .TP
 237 .PD 0
 238 .BR \-\-max\-chars "=\fImax-chars\fR"
 239 .TP
 240 .PD
 241 .BI \-s " max-chars"
 242 Use at most \fImax-chars\fR characters per command line, including the
 243 command and initial-arguments and the terminating nulls at the ends of
 244 the argument strings.  The largest allowed value is system-dependent,
 245 and is calculated as the argument length limit for exec, less the size
 246 of your environment, less 2048 bytes of headroom.  If this value is
 247 more than 128KiB, 128Kib is used as the default value; otherwise, the
 248 default value is the maximum.  1KiB is 1024 bytes.
 249 .TP
 250 .PD 0
 251 .B \-\-verbose
 252 .TP
 253 .PD
 254 .B \-t
 255 Print the command line on the standard error output before executing
 256 it.
 257 .TP
 258 .B "\-\-version"
 259 Print the version number of
 260 .B xargs
 261 and exit.
 262 .TP
 263 .B "\-\-show\\-limits"
 264 Display the limits on the command-line length which are imposed by the
 265 operating system,
 266 .BR xargs '
 267 choice of buffer size and the
 268 .B \-s
 269 option.  Pipe the input from
 270 .I /dev/null
 271 (and perhaps specify
 272 .BR --no-run-if-empty )
 273 if you don't want
 274 .B xargs
 275 to do anything.
 276 .TP
 277 .PD 0
 278 .B \-\-exit
 279 .TP
 280 .PD
 281 .B \-x
 282 Exit if the size (see the
 283 .B \-s
 284 option) is exceeded.
 285 .TP
 286 .PD 0
 287 .BR \-\-max\-procs "=\fImax-procs\fR"
 288 .TP
 289 .PD
 290 .BI \-P " max-procs"
 291 Run up to
 292 .I max-procs
 293 processes at a time; the default is 1.  If
 294 .I max-procs
 295 is 0,
 296 .B xargs
 297 will run as many processes as
 298 possible at a time.  Use the
 299 .B \-n
 300 option with
 301 .BR \-P ;
 302 otherwise chances are that only one exec will be done.
 303 .SH "EXAMPLES"
 304 .nf
 305 .B find /tmp \-name core \-type f \-print | xargs /bin/rm \-f
 306
 307 .fi
 308 Find files named
 309 .B core
 310 in or below the directory
 311 .B /tmp
 312 and delete them.  Note that this will work incorrectly if there are
 313 any filenames containing newlines or spaces.
 314 .P
 315 .B find /tmp \-name core \-type f \-print0 | xargs \-0 /bin/rm \-f
 316
 317 .fi
 318 Find files named
 319 .B core
 320 in or below the directory
 321 .B /tmp
 322 and delete them, processing filenames in such a way that file or
 323 directory names containing spaces or newlines are correctly handled.
 324 .P
 325 .nf
 326 .B cut \-d: \-f1 < /etc/passwd | sort | xargs echo
 327
 328 .fi
 329 Generates a compact listing of all the users on the system.
 330 .SH "EXIT STATUS"
 331 .B xargs
 332 exits with the following status:
 333 .nf
 334 0 if it succeeds
 335 123 if any invocation of the command exited with status 1-125
 336 124 if the command exited with status 255
 337 125 if the command is killed by a signal
 338 126 if the command cannot be run
 339 127 if the command is not found
 340 1 if some other error occurred.
 341 .fi
 342 .P
 343 Exit codes greater than 128 are used by the shell to indicate that
 344 a program died due to a fatal signal.
 345 .SH "STANDARDS CONFORMANCE"
 346 As of GNU xargs version 4.2.9, the default behaviour of
 347 .B xargs
 348 is not to have a logical end-of-file marker.  POSIX (IEEE Std 1003.1,
 349 2004 Edition) allows this.
 350 .P
 351 The \-l and \-i options appear in the 1997 version of the POSIX
 352 standard, but do not appear in the 2004 version of the standard.
 353 Therefore you should use \-L and \-I instead, respectively.
 354 .P
 355 The POSIX stadard allows implementations to have a limit on the size
 356 of arguments to the
 357 .B exec
 358 functions.  This limit could be as low as 4096 bytes including the size of the
 359 environment.  For scripts to be portable, they must not rely on a
 360 larger value.  However, I know of no implementation whose actual limit
 361 is that small.  The
 362 .B \-\-show\-limits
 363 option can be used to discover the actual limits in force on the
 364 current system.
 365
 366
 367 .SH "SEE ALSO"
 368 \fBfind\fP(1), \fBlocate\fP(1), \fBlocatedb\fP(5), \fBupdatedb\fP(1),
 369 \fBFinding Files\fP (on-line in Info, or printed)
 370 .SH "BUGS"
 371 The
 372 .B \-L
 373 option is incompatible with the
 374 .B \-I
 375 option, but perhaps should not be.
 376 .P
 377 It is not possible for
 378 .B xargs
 379 to be used securely, since there will always be a time gap between the
 380 production of the list of input files and their use in the commands
 381 that
 382 .B xargs
 383 issues.  If other users have access to the system, they can manipulate
 384 the filesystem during this time window to force the action of the
 385 commands
 386 .B xargs
 387 runs to apply to files that you didn't intend.  For a more detailed
 388 discussion of this and related problems, please refer to the
 389 ``Security Considerations'' chapter in the findutils Texinfo
 390 documentation.  The
 391 .B \-execdir
 392 option of
 393 .B find
 394 can often be used as a more secure alternative.
 395
 396 When you use the
 397 .B \-I
 398 option, each line read from the input is buffered
 399 internally.   This means that there is an upper limit on the length
 400 of input line that
 401 .B xargs
 402 will accept when used with the
 403 .B \-I
 404 option.  To work around this
 405 limitation, you can use the
 406 .B \-s
 407 option to increase the amount of
 408 buffer space that
 409 .B xargs
 410 uses, and you can also use an extra invocation of
 411 .B xargs
 412 to ensure that very long lines do not occur.
 413 For example:
 414 .P
 415 .B somecommand | xargs \-s 50000 echo | xargs \-I '{}' \-s 100000 rm '{}'
 416 .P
 417 Here, the first invocation of
 418 .B xargs
 419 has no input line length limit
 420 because it doesn't use the
 421 .B \-i
 422 option.  The second invocation of
 423 .B xargs
 424 does have such a limit, but we have ensured that the it never encounters
 425 a line which is longer than it can handle.   This is not an ideal
 426 solution.  Instead, the
 427 .B \-i
 428 option should not impose a line length
 429 limit, which is why this discussion appears in the BUGS section.
 430 The problem doesn't occur with the output of
 431 .BR find (1)
 432 because it emits just one filename per line.
 433 .P
 434 The best way to report a bug is to use the form at
 435 http://savannah.gnu.org/bugs/?group=findutils.
 436 The reason for this is that you will then be able to track progress in
 437 fixing the problem.   Other comments about \fBxargs\fP(1) and about
 438 the findutils package in general can be sent to the
 439 .I bug\-findutils
 440 mailing list.  To join the list, send email to
 441 .IR bug\-findutils\-request@gnu.org .