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: src/usr.bin/xargs/xargs.1,v 1.6.2.12 2003/06/01 21:40:35 mux Exp $
  38 .\" $xMach: xargs.1,v 1.2 2002/02/23 05:23:37 tim Exp $
  39 .\"
  40 .Dd May 7, 2001
  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 s Ar size
  61 .Op Ar utility Op Ar argument ...
  62 .Sh DESCRIPTION
  63 The
  64 .Nm
  65 utility reads space, tab, newline and end-of-file delimited strings
  66 from the standard input and executes
  67 .Ar utility
  68 with the strings as
  69 arguments.
  70 .Pp
  71 Any arguments specified on the command line are given to
  72 .Ar utility
  73 upon each invocation, followed by some number of the arguments read
  74 from the standard input of
  75 .Nm .
  76 The utility
  77 is repeatedly executed until standard input is exhausted.
  78 .Pp
  79 Spaces, tabs and newlines may be embedded in arguments using single
  80 (``\ '\ '')
  81 or double (``"'') quotes or backslashes (``\e'').
  82 Single quotes escape all non-single quote characters, excluding newlines,
  83 up to the matching single quote.
  84 Double quotes escape all non-double quote characters, excluding newlines,
  85 up to the matching double quote.
  86 Any single character, including newlines, may be escaped by a backslash.
  87 .Pp
  88 The options are as follows:
  89 .Bl -tag -width indent
  90 .It Fl 0
  91 Change
  92 .Nm
  93 to expect NUL
  94 (``\\0'')
  95 characters as separators, instead of spaces and newlines.
  96 This is expected to be used in concert with the
  97 .Fl print0
  98 function in
  99 .Xr find 1 .
 100 .It Fl E Ar eofstr
 101 Use
 102 .Ar eofstr
 103 as a logical EOF marker.
 104 .It Fl I Ar replstr
 105 Execute
 106 .Ar utility
 107 for each input line, replacing one or more occurrences of
 108 .Ar replstr
 109 in up to
 110 .Ar replacements
 111 (or 5 if no
 112 .Fl R
 113 flag is specified) arguments to
 114 .Ar utility
 115 with the entire line of input.
 116 The resulting arguments, after replacement is done, will not be allowed to grow
 117 beyond 255 bytes; this is implemented by concatenating as much of the argument
 118 containing
 119 .Ar replstr
 120 as possible, to the constructed arguments to
 121 .Ar utility ,
 122 up to 255 bytes.
 123 The 255 byte limit does not apply to arguments to
 124 .Ar utility
 125 which do not contain
 126 .Ar replstr ,
 127 and furthermore, no replacement will be done on
 128 .Ar utility
 129 itself.
 130 Implies
 131 .Fl x .
 132 .It Fl J Ar replstr
 133 If this option is specified,
 134 .Nm
 135 will use the data read from standard input to replace the first occurrence of
 136 .Ar replstr
 137 instead of appending that data after all other arguments.
 138 This option will not effect how many arguments will be read from input
 139 .Pq Fl n ,
 140 or the size of the command(s)
 141 .Nm
 142 will generate
 143 .Pq Fl s .
 144 The option just moves where those arguments will be placed in the command(s)
 145 that are executed.
 146 The
 147 .Ar replstr
 148 must show up as a distinct
 149 .Ar argument
 150 to
 151 .Nm .
 152 It will not be recognized if, for instance, it is in the middle of a
 153 quoted string.
 154 Furthermore, only the first occurrence of the
 155 .Ar replstr
 156 will be replaced.
 157 For example, the following command will copy the list of files and
 158 directories which start with an uppercase letter in the current
 159 directory to
 160 .Pa destdir :
 161 .Pp
 162 .Dl /bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir
 163 .Pp
 164 .It Fl L Ar number
 165 Call
 166 .Ar utility
 167 for every
 168 .Ar number
 169 lines read.
 170 If EOF is reached and fewer lines have been read than
 171 .Ar number
 172 then
 173 .Ar utility
 174 will be called with the available lines.
 175 .It Fl n Ar number
 176 Set the maximum number of arguments taken from standard input for each
 177 invocation of
 178 .Ar utility .
 179 An invocation of
 180 .Ar utility
 181 will use less than
 182 .Ar number
 183 standard input arguments if the number of bytes accumulated (see the
 184 .Fl s
 185 option) exceeds the specified
 186 .Ar size
 187 or there are fewer than
 188 .Ar number
 189 arguments remaining for the last invocation of
 190 .Ar utility .
 191 The current default value for
 192 .Ar number
 193 is 5000.
 194 .It Fl o
 195 Reopen stdin as
 196 .Dq /dev/tty
 197 in the child process before executing the command.
 198 This is useful if you want
 199 .Nm
 200 to run an interactive application.
 201 .It Fl p
 202 Echo each command to be executed and ask the user whether it should be
 203 executed.
 204 An affirmative response,
 205 .Ql y
 206 in the POSIX locale,
 207 causes the command to be executed, any other response causes it to be
 208 skipped.
 209 No commands are executed if the process is not attached to a terminal.
 210 .It Fl R Ar replacements
 211 Specify the maximum number of arguments that
 212 .Fl I
 213 will do replacement in.
 214 .It Fl s Ar size
 215 Set the maximum number of bytes for the command line length provided to
 216 .Ar utility .
 217 The sum of the length of the utility name, the arguments passed to
 218 .Ar utility
 219 (including
 220 .Dv NULL
 221 terminators) and the current environment will be less than or equal to
 222 this number.
 223 The current default value for
 224 .Ar size
 225 is
 226 .Dv ARG_MAX
 227 - 4096.
 228 .It Fl t
 229 Echo the command to be executed to standard error immediately before it
 230 is executed.
 231 .It Fl x
 232 Force
 233 .Nm
 234 to terminate immediately if a command line containing
 235 .Ar number
 236 arguments will not fit in the specified (or default) command line length.
 237 .El
 238 .Pp
 239 If
 240 .Ar utility
 241 is omitted,
 242 .Xr echo 1
 243 is used.
 244 .Pp
 245 Undefined behavior may occur if
 246 .Ar utility
 247 reads from the standard input.
 248 .Pp
 249 The
 250 .Nm
 251 utility exits immediately (without processing any further input) if a
 252 command line cannot be assembled,
 253 .Ar utility
 254 cannot be invoked, an invocation of
 255 .Ar utility
 256 is terminated by a signal,
 257 or an invocation of
 258 .Ar utility
 259 exits with a value of 255.
 260 .Sh DIAGNOSTICS
 261 The
 262 .Nm
 263 utility exits with a value of 0 if no error occurs.
 264 If
 265 .Ar utility
 266 cannot be found,
 267 .Nm
 268 exits with a value of 127, otherwise if
 269 .Ar utility
 270 cannot be executed,
 271 .Nm
 272 exits with a value of 126.
 273 If any other error occurs,
 274 .Nm
 275 exits with a value of 1.
 276 .Sh SEE ALSO
 277 .Xr echo 1 ,
 278 .Xr find 1 ,
 279 .Xr execvp 3
 280 .Sh STANDARDS
 281 The
 282 .Nm
 283 utility is expected to be
 284 .St -p1003.2
 285 compliant.
 286 The
 287 .Fl J , o
 288 and
 289 .Fl R
 290 options are non-standard
 291 .Fx
 292 extensions which may not be available on other operating systems.
 293 .Sh HISTORY
 294 The
 295 .Nm
 296 command appeared in PWB UNIX.
 297 .Sh BUGS
 298 If
 299 .Ar utility
 300 attempts to invoke another command such that the number of arguments or the
 301 size of the environment is increased, it risks
 302 .Xr execvp 3
 303 failing with
 304 .Er E2BIG .