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