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. 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: src/usr.bin/xargs/xargs.1,v 1.6.2.12 2003/06/01 21:40:35 mux Exp $
  34 .\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
  35 .\"
  36 .Dd March 1, 2017
  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 0opt
  45 .Op Fl E Ar eofstr
  46 .Oo
  47 .Fl I Ar replstr
  48 .Op Fl R Ar replacements
  49 .Oc
  50 .Op Fl J Ar replstr
  51 .Op Fl L Ar number
  52 .Oo
  53 .Fl n Ar number
  54 .Op Fl x
  55 .Oc
  56 .Op Fl P Ar maxjobs
  57 .Op Fl s Ar size
  58 .Op Ar utility Op Ar argument ...
  59 .Sh DESCRIPTION
  60 The
  61 .Nm
  62 utility reads space, tab, newline and end-of-file delimited strings
  63 from the standard input and executes
  64 .Ar utility
  65 with the strings as
  66 arguments.
  67 .Pp
  68 Any arguments specified on the command line are given to
  69 .Ar utility
  70 upon each invocation, followed by some number of the arguments read
  71 from the standard input of
  72 .Nm .
  73 The utility
  74 is repeatedly executed 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 255 bytes; this is implemented by concatenating as much of the argument
 115 containing
 116 .Ar replstr
 117 as possible, to the constructed arguments to
 118 .Ar utility ,
 119 up to 255 bytes.
 120 The 255 byte limit does not apply to arguments to
 121 .Ar utility
 122 which do not contain
 123 .Ar replstr ,
 124 and furthermore, no replacement will be done on
 125 .Ar utility
 126 itself.
 127 Implies
 128 .Fl x .
 129 .It Fl J Ar replstr
 130 If this option is specified,
 131 .Nm
 132 will use the data read from standard input to replace the first occurrence of
 133 .Ar replstr
 134 instead of appending that data after all other arguments.
 135 This option will not affect how many arguments will be read from input
 136 .Pq Fl n ,
 137 or the size of the command(s)
 138 .Nm
 139 will generate
 140 .Pq Fl s .
 141 The option just moves where those arguments will be placed in the command(s)
 142 that are executed.
 143 The
 144 .Ar replstr
 145 must show up as a distinct
 146 .Ar argument
 147 to
 148 .Nm .
 149 It will not be recognized if, for instance, it is in the middle of a
 150 quoted string.
 151 Furthermore, only the first occurrence of the
 152 .Ar replstr
 153 will be replaced.
 154 For example, the following command will copy the list of files and
 155 directories which start with an uppercase letter in the current
 156 directory to
 157 .Pa destdir :
 158 .Pp
 159 .Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir
 160 .It Fl L Ar number
 161 Call
 162 .Ar utility
 163 for every
 164 .Ar number
 165 lines read.
 166 If EOF is reached and fewer lines have been read than
 167 .Ar number
 168 then
 169 .Ar utility
 170 will be called with the available lines.
 171 .It Fl n Ar number
 172 Set the maximum number of arguments taken from standard input for each
 173 invocation of
 174 .Ar utility .
 175 An invocation of
 176 .Ar utility
 177 will use less than
 178 .Ar number
 179 standard input arguments if the number of bytes accumulated (see the
 180 .Fl s
 181 option) exceeds the specified
 182 .Ar size
 183 or there are fewer than
 184 .Ar number
 185 arguments remaining for the last invocation of
 186 .Ar utility .
 187 The current default value for
 188 .Ar number
 189 is 5000.
 190 .It Fl o
 191 Reopen stdin as
 192 .Pa /dev/tty
 193 in the child process before executing the command.
 194 This is useful if you want
 195 .Nm
 196 to run an interactive application.
 197 .It Fl P Ar maxprocs
 198 Parallel mode: run at most
 199 .Ar maxprocs
 200 invocations of
 201 .Ar utility
 202 at once.
 203 .It Fl p
 204 Echo each command to be executed and ask the user whether it should be
 205 executed.
 206 An affirmative response,
 207 .Ql y
 208 in the POSIX locale,
 209 causes the command to be executed, any other response causes it to be
 210 skipped.
 211 No commands are executed if the process is not attached to a terminal.
 212 .It Fl r
 213 Compatibility with GNU
 214 .Nm .
 215 The GNU version of
 216 .Nm
 217 runs the
 218 .Ar utility
 219 argument at least once, even if
 220 .Nm
 221 input is empty, and it supports a
 222 .Fl r
 223 option to inhibit this behavior.
 224 The
 225 .Dx
 226 version of
 227 .Nm
 228 does not run the
 229 .Ar utility
 230 argument on empty input, but it supports the
 231 .Fl r
 232 option for command-line compatibility with GNU
 233 .Nm ,
 234 but the
 235 .Fl r
 236 option does nothing in the
 237 .Dx
 238 version of
 239 .Nm .
 240 .It Fl R Ar replacements
 241 Specify the maximum number of arguments that
 242 .Fl I
 243 will do replacement in.
 244 .It Fl s Ar size
 245 Set the maximum number of bytes for the command line length provided to
 246 .Ar utility .
 247 The sum of the length of the utility name, the arguments passed to
 248 .Ar utility
 249 (including
 250 .Dv NULL
 251 terminators) and the current environment will be less than or equal to
 252 this number.
 253 The current default value for
 254 .Ar size
 255 is
 256 .Dv ARG_MAX
 257 - 4096.
 258 .It Fl t
 259 Echo the command to be executed to standard error immediately before it
 260 is executed.
 261 .It Fl x
 262 Force
 263 .Nm
 264 to terminate immediately if a command line containing
 265 .Ar number
 266 arguments will not fit in the specified (or default) command line length.
 267 .El
 268 .Pp
 269 If
 270 .Ar utility
 271 is omitted,
 272 .Xr echo 1
 273 is used.
 274 .Pp
 275 Undefined behavior may occur if
 276 .Ar utility
 277 reads from the standard input.
 278 .Pp
 279 The
 280 .Nm
 281 utility exits immediately (without processing any further input) if a
 282 command line cannot be assembled,
 283 .Ar utility
 284 cannot be invoked, an invocation of
 285 .Ar utility
 286 is terminated by a signal,
 287 or an invocation of
 288 .Ar utility
 289 exits with a value of 255.
 290 .Sh EXIT STATUS
 291 The
 292 .Nm
 293 utility exits with a value of 0 if no error occurs.
 294 If
 295 .Ar utility
 296 cannot be found,
 297 .Nm
 298 exits with a value of 127, otherwise if
 299 .Ar utility
 300 cannot be executed,
 301 .Nm
 302 exits with a value of 126.
 303 If any other error occurs,
 304 .Nm
 305 exits with a value of 1.
 306 .Sh SEE ALSO
 307 .Xr echo 1 ,
 308 .Xr find 1 ,
 309 .Xr execvp 3
 310 .Sh STANDARDS
 311 The
 312 .Nm
 313 utility is expected to be
 314 .St -p1003.2
 315 compliant.
 316 The
 317 .Fl J , o , P
 318 and
 319 .Fl R
 320 options are non-standard
 321 .Dx
 322 extensions which may not be available on other operating systems.
 323 .Sh HISTORY
 324 The
 325 .Nm
 326 command appeared in PWB
 327 .Ux .
 328 .Sh BUGS
 329 If
 330 .Ar utility
 331 attempts to invoke another command such that the number of arguments or the
 332 size of the environment is increased, it risks
 333 .Xr execvp 3
 334 failing with
 335 .Er E2BIG .