usr.bin/xargs/xargs.1

   1 .\" Copyright (c) 1990, 1991, 1993
   2 .\"     The Regents of the University of California.  All rights reserved.
   3 .\"
   4 .\" This code is derived from software contributed to Berkeley by
   5 .\" John B. Roll Jr. and the Institute of Electrical and Electronics
   6 .\" Engineers, Inc.
   7 .\"
   8 .\" Redistribution and use in source and binary forms, with or without
   9 .\" modification, are permitted provided that the following conditions
  10 .\" are met:
  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. All advertising materials mentioning features or use of this software
  17 .\"    must display the following acknowledgement:
  18 .\"     This product includes software developed by the University of
  19 .\"     California, Berkeley and its contributors.
  20 .\" 4. Neither the name of the University nor the names of its contributors
  21 .\"    may be used to endorse or promote products derived from this software
  22 .\"    without specific prior written permission.
  23 .\"
  24 .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
  25 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  26 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  27 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
  28 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  29 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  30 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  31 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  32 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  33 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  34 .\" SUCH DAMAGE.
  35 .\"
  36 .\"     @(#)xargs.1     8.1 (Berkeley) 6/6/93
  37 .\" $FreeBSD$
  38 .\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
  39 .\"
  40 .Dd January 26, 2008
  41 .Dt XARGS 1
  42 .Os
  43 .Sh NAME
  44 .Nm xargs
  45 .Nd "construct argument list(s) and execute utility"
  46 .Sh SYNOPSIS
  47 .Nm
  48 .Op Fl 0oprt
  49 .Op Fl E Ar eofstr
  50 .Oo
  51 .Fl I Ar replstr
  52 .Op Fl R Ar replacements
  53 .Op Fl S Ar replsize
  54 .Oc
  55 .Op Fl J Ar replstr
  56 .Op Fl L Ar number
  57 .Oo
  58 .Fl n Ar number
  59 .Op Fl x
  60 .Oc
  61 .Op Fl P Ar maxprocs
  62 .Op Fl s Ar size
  63 .Op Ar utility Op Ar argument ...
  64 .Sh DESCRIPTION
  65 The
  66 .Nm
  67 utility reads space, tab, newline and end-of-file delimited strings
  68 from the standard input and executes
  69 .Ar utility
  70 with the strings as
  71 arguments.
  72 .Pp
  73 Any arguments specified on the command line are given to
  74 .Ar utility
  75 upon each invocation, followed by some number of the arguments read
  76 from the standard input of
  77 .Nm .
  78 This is repeated until standard input is exhausted.
  79 .Pp
  80 Spaces, tabs and newlines may be embedded in arguments using single
  81 (``\ '\ '')
  82 or double (``"'') quotes or backslashes (``\e'').
  83 Single quotes escape all non-single quote characters, excluding newlines,
  84 up to the matching single quote.
  85 Double quotes escape all non-double quote characters, excluding newlines,
  86 up to the matching double quote.
  87 Any single character, including newlines, may be escaped by a backslash.
  88 .Pp
  89 The options are as follows:
  90 .Bl -tag -width indent
  91 .It Fl 0
  92 Change
  93 .Nm
  94 to expect NUL
  95 (``\\0'')
  96 characters as separators, instead of spaces and newlines.
  97 This is expected to be used in concert with the
  98 .Fl print0
  99 function in
 100 .Xr find 1 .
 101 .It Fl E Ar eofstr
 102 Use
 103 .Ar eofstr
 104 as a logical EOF marker.
 105 .It Fl I Ar replstr
 106 Execute
 107 .Ar utility
 108 for each input line, replacing one or more occurrences of
 109 .Ar replstr
 110 in up to
 111 .Ar replacements
 112 (or 5 if no
 113 .Fl R
 114 flag is specified) arguments to
 115 .Ar utility
 116 with the entire line of input.
 117 The resulting arguments, after replacement is done, will not be allowed to grow
 118 beyond
 119 .Ar replsize
 120 (or 255 if no
 121 .Fl S
 122 flag is specified)
 123 bytes; this is implemented by concatenating as much of the argument
 124 containing
 125 .Ar replstr
 126 as possible, to the constructed arguments to
 127 .Ar utility ,
 128 up to
 129 .Ar replsize
 130 bytes.
 131 The size limit does not apply to arguments to
 132 .Ar utility
 133 which do not contain
 134 .Ar replstr ,
 135 and furthermore, no replacement will be done on
 136 .Ar utility
 137 itself.
 138 Implies
 139 .Fl x .
 140 .It Fl J Ar replstr
 141 If this option is specified,
 142 .Nm
 143 will use the data read from standard input to replace the first occurrence of
 144 .Ar replstr
 145 instead of appending that data after all other arguments.
 146 This option will not affect how many arguments will be read from input
 147 .Pq Fl n ,
 148 or the size of the command(s)
 149 .Nm
 150 will generate
 151 .Pq Fl s .
 152 The option just moves where those arguments will be placed in the command(s)
 153 that are executed.
 154 The
 155 .Ar replstr
 156 must show up as a distinct
 157 .Ar argument
 158 to
 159 .Nm .
 160 It will not be recognized if, for instance, it is in the middle of a
 161 quoted string.
 162 Furthermore, only the first occurrence of the
 163 .Ar replstr
 164 will be replaced.
 165 For example, the following command will copy the list of files and
 166 directories which start with an uppercase letter in the current
 167 directory to
 168 .Pa destdir :
 169 .Pp
 170 .Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir
 171 .Pp
 172 .It Fl L Ar number
 173 Call
 174 .Ar utility
 175 for every
 176 .Ar number
 177 lines read.
 178 If EOF is reached and fewer lines have been read than
 179 .Ar number
 180 then
 181 .Ar utility
 182 will be called with the available lines.
 183 .It Fl n Ar number
 184 Set the maximum number of arguments taken from standard input for each
 185 invocation of
 186 .Ar utility .
 187 An invocation of
 188 .Ar utility
 189 will use less than
 190 .Ar number
 191 standard input arguments if the number of bytes accumulated (see the
 192 .Fl s
 193 option) exceeds the specified
 194 .Ar size
 195 or there are fewer than
 196 .Ar number
 197 arguments remaining for the last invocation of
 198 .Ar utility .
 199 The current default value for
 200 .Ar number
 201 is 5000.
 202 .It Fl o
 203 Reopen stdin as
 204 .Pa /dev/tty
 205 in the child process before executing the command.
 206 This is useful if you want
 207 .Nm
 208 to run an interactive application.
 209 .It Fl P Ar maxprocs
 210 Parallel mode: run at most
 211 .Ar maxprocs
 212 invocations of
 213 .Ar utility
 214 at once.
 215 .It Fl p
 216 Echo each command to be executed and ask the user whether it should be
 217 executed.
 218 An affirmative response,
 219 .Ql y
 220 in the POSIX locale,
 221 causes the command to be executed, any other response causes it to be
 222 skipped.
 223 No commands are executed if the process is not attached to a terminal.
 224 .It Fl r
 225 Compatibility with GNU
 226 .Nm .
 227 The GNU version of
 228 .Nm
 229 runs the
 230 .Ar utility
 231 argument at least once, even if
 232 .Nm
 233 input is empty, and it supports a
 234 .Fl r
 235 option to inhibit this behavior.
 236 The
 237 .Fx
 238 version of
 239 .Nm
 240 does not run the
 241 .Ar utility
 242 argument on empty input, but it supports the
 243 .Fl r
 244 option for command-line compatibility with GNU
 245 .Nm ,
 246 but the
 247 .Fl r
 248 option does nothing in the
 249 .Fx
 250 version of
 251 .Nm .
 252 .It Fl R Ar replacements
 253 Specify the maximum number of arguments that
 254 .Fl I
 255 will do replacement in.
 256 If
 257 .Ar replacements
 258 is negative, the number of arguments in which to replace is unbounded.
 259 .It Fl S Ar replsize
 260 Specify the amount of space (in bytes) that
 261 .Fl I
 262 can use for replacements.
 263 The default for
 264 .Ar replsize
 265 is 255.
 266 .It Fl s Ar size
 267 Set the maximum number of bytes for the command line length provided to
 268 .Ar utility .
 269 The sum of the length of the utility name, the arguments passed to
 270 .Ar utility
 271 (including
 272 .Dv NULL
 273 terminators) and the current environment will be less than or equal to
 274 this number.
 275 The current default value for
 276 .Ar size
 277 is
 278 .Dv ARG_MAX
 279 - 4096.
 280 .It Fl t
 281 Echo the command to be executed to standard error immediately before it
 282 is executed.
 283 .It Fl x
 284 Force
 285 .Nm
 286 to terminate immediately if a command line containing
 287 .Ar number
 288 arguments will not fit in the specified (or default) command line length.
 289 .El
 290 .Pp
 291 If
 292 .Ar utility
 293 is omitted,
 294 .Xr echo 1
 295 is used.
 296 .Pp
 297 Undefined behavior may occur if
 298 .Ar utility
 299 reads from the standard input.
 300 .Pp
 301 The
 302 .Nm
 303 utility exits immediately (without processing any further input) if a
 304 command line cannot be assembled,
 305 .Ar utility
 306 cannot be invoked, an invocation of
 307 .Ar utility
 308 is terminated by a signal,
 309 or an invocation of
 310 .Ar utility
 311 exits with a value of 255.
 312 .Sh EXIT STATUS
 313 The
 314 .Nm
 315 utility exits with a value of 0 if no error occurs.
 316 If
 317 .Ar utility
 318 cannot be found,
 319 .Nm
 320 exits with a value of 127, otherwise if
 321 .Ar utility
 322 cannot be executed,
 323 .Nm
 324 exits with a value of 126.
 325 If any other error occurs,
 326 .Nm
 327 exits with a value of 1.
 328 .Sh SEE ALSO
 329 .Xr echo 1 ,
 330 .Xr find 1 ,
 331 .Xr execvp 3
 332 .Sh STANDARDS
 333 The
 334 .Nm
 335 utility is expected to be
 336 .St -p1003.2
 337 compliant.
 338 The
 339 .Fl J , o , P, R
 340 and
 341 .Fl S
 342 options are non-standard
 343 .Fx
 344 extensions which may not be available on other operating systems.
 345 .Sh HISTORY
 346 The
 347 .Nm
 348 utility appeared in PWB UNIX.
 349 .Sh BUGS
 350 If
 351 .Ar utility
 352 attempts to invoke another command such that the number of arguments or the
 353 size of the environment is increased, it risks
 354 .Xr execvp 3
 355 failing with
 356 .Er E2BIG .
 357 .Pp
 358 The
 359 .Nm
 360 utility does not take multibyte characters into account when performing
 361 string comparisons for the
 362 .Fl I
 363 and
 364 .Fl J
 365 options, which may lead to incorrect results in some locales.