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