Annotation of src/usr.bin/xargs/xargs.1, Revision 1.17
1.17 ! otto 1: .\" $OpenBSD: xargs.1,v 1.16 2006/02/14 12:18:21 otto Exp $
1.12 millert 2: .\" $FreeBSD: xargs.1,v 1.30 2003/05/21 21:07:28 ru Exp $$
1.1 deraadt 3: .\"
4: .\" Copyright (c) 1990, 1991, 1993
5: .\" The Regents of the University of California. All rights reserved.
6: .\"
7: .\" This code is derived from software contributed to Berkeley by
8: .\" John B. Roll Jr. and the Institute of Electrical and Electronics
9: .\" Engineers, Inc.
10: .\"
11: .\" Redistribution and use in source and binary forms, with or without
12: .\" modification, are permitted provided that the following conditions
13: .\" are met:
14: .\" 1. Redistributions of source code must retain the above copyright
15: .\" notice, this list of conditions and the following disclaimer.
16: .\" 2. Redistributions in binary form must reproduce the above copyright
17: .\" notice, this list of conditions and the following disclaimer in the
18: .\" documentation and/or other materials provided with the distribution.
1.11 millert 19: .\" 3. Neither the name of the University nor the names of its contributors
1.1 deraadt 20: .\" may be used to endorse or promote products derived from this software
21: .\" without specific prior written permission.
22: .\"
23: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
24: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
25: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
26: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
27: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
28: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
29: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
30: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
31: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
32: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
33: .\" SUCH DAMAGE.
34: .\"
35: .\" @(#)xargs.1 8.1 (Berkeley) 6/6/93
36: .\"
1.12 millert 37: .Dd May 7, 2001
1.1 deraadt 38: .Dt XARGS 1
39: .Os
40: .Sh NAME
41: .Nm xargs
42: .Nd "construct argument list(s) and execute utility"
43: .Sh SYNOPSIS
1.13 jmc 44: .Nm xargs
45: .Bk -words
1.14 brad 46: .Op Fl 0oprt
1.12 millert 47: .Op Fl E Ar eofstr
48: .Oo
49: .Fl I Ar replstr
50: .Op Fl R Ar replacements
51: .Oc
52: .Op Fl J Ar replstr
53: .Op Fl L Ar number
54: .Oo
1.1 deraadt 55: .Fl n Ar number
1.12 millert 56: .Op Fl x
1.1 deraadt 57: .Oc
1.15 jmc 58: .Op Fl P Ar maxprocs
1.1 deraadt 59: .Op Fl s Ar size
1.12 millert 60: .Op Ar utility Op Ar argument ...
1.13 jmc 61: .Ek
1.1 deraadt 62: .Sh DESCRIPTION
63: The
1.7 aaron 64: .Nm
1.12 millert 65: utility reads space, tab, newline, and end-of-file delimited strings
1.1 deraadt 66: from the standard input and executes the specified
67: .Ar utility
1.12 millert 68: with the strings as
1.1 deraadt 69: arguments.
70: .Pp
1.12 millert 71: Any arguments specified on the command line are given to the
1.1 deraadt 72: .Ar utility
73: upon each invocation, followed by some number of the arguments read
74: from standard input.
75: The
76: .Ar utility
1.14 brad 77: is repeatedly executed one or more times until standard input
78: is exhausted.
1.1 deraadt 79: .Pp
80: Spaces, tabs and newlines may be embedded in arguments using single
1.7 aaron 81: .Pq Ql '
82: or double
83: .Pq Ql \&"
84: quotes or backslashes
85: .Pq Ql \e .
1.1 deraadt 86: Single quotes escape all non-single quote characters, excluding newlines,
87: up to the matching single quote.
88: Double quotes escape all non-double quote characters, excluding newlines,
89: up to the matching double quote.
90: Any single character, including newlines, may be escaped by a backslash.
91: .Pp
92: The options are as follows:
1.10 aaron 93: .Bl -tag -width Ds
1.2 deraadt 94: .It Fl 0
1.12 millert 95: Change
1.7 aaron 96: .Nm
1.2 deraadt 97: to expect NUL
1.7 aaron 98: .Pq Ql \e0
1.5 deraadt 99: characters as separators, instead of spaces and newlines.
1.2 deraadt 100: This is expected to be used in concert with the
1.3 deraadt 101: .Fl print0
102: function in
1.7 aaron 103: .Xr find 1 .
1.12 millert 104: .It Fl E Ar eofstr
105: Use
106: .Ar eofstr
107: as a logical EOF marker.
108: .It Fl I Ar replstr
109: Execute
110: .Ar utility
111: for each input line, replacing one or more occurrences of
112: .Ar replstr
113: in up to
114: .Ar replacements
115: (or 5 if no
116: .Fl R
117: flag is specified) arguments to
118: .Ar utility
119: with the entire line of input.
120: The resulting arguments, after replacement is done, will not be allowed to grow
121: beyond 255 bytes; this is implemented by concatenating as much of the argument
122: containing
123: .Ar replstr
124: as possible, to the constructed arguments to
125: .Ar utility ,
126: up to 255 bytes.
127: The 255 byte 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 effect 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 xargs .
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
1.13 jmc 166: .Dl "/bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir"
1.12 millert 167: .It Fl L Ar number
168: Call
169: .Ar utility
170: for every
171: .Ar number
172: of lines read.
173: If EOF is reached and fewer than
174: .Ar number
175: lines have been read then
176: .Ar utility
177: will be called with the available lines.
1.1 deraadt 178: .It Fl n Ar number
179: Set the maximum number of arguments taken from standard input for each
1.12 millert 180: invocation of
181: .Ar utility .
1.1 deraadt 182: An invocation of
183: .Ar utility
184: will use less than
185: .Ar number
186: standard input arguments if the number of bytes accumulated (see the
187: .Fl s
188: option) exceeds the specified
189: .Ar size
190: or there are fewer than
191: .Ar number
192: arguments remaining for the last invocation of
193: .Ar utility .
194: The current default value for
195: .Ar number
196: is 5000.
1.12 millert 197: .It Fl o
198: Reopen stdin as
199: .Pa /dev/tty
200: in the child process before executing the command.
201: This is useful if you want
202: .Nm
203: to run an interactive application.
204: .It Fl P Ar maxprocs
205: Parallel mode: run at most
206: .Ar maxprocs
207: invocations of
208: .Ar utility
209: at once.
210: .It Fl p
211: Echo each command to be executed and ask the user whether it should be
212: executed.
213: An affirmative response,
214: .Ql y
215: in the POSIX locale,
216: causes the command to be executed, any other response causes it to be
217: skipped.
218: No commands are executed if the process is not attached to a terminal.
219: .It Fl R Ar replacements
220: Specify the maximum number of arguments that
221: .Fl I
222: will do replacement in.
223: If
224: .Ar replacements
225: is negative, the number of arguments in which to replace is unbounded.
1.14 brad 226: .It Fl r
227: Do not run the command if there are no arguments.
228: Normally the command is executed at least once
229: even if there are no arguments.
1.1 deraadt 230: .It Fl s Ar size
1.12 millert 231: Set the maximum number of bytes for the command line length provided to
1.1 deraadt 232: .Ar utility .
1.12 millert 233: The sum of the length of the utility name, the arguments passed to
1.1 deraadt 234: .Ar utility
1.12 millert 235: (including
236: .Dv NUL
237: terminators) and the current environment will be less than or equal to
238: this number.
1.1 deraadt 239: The current default value for
240: .Ar size
241: is
242: .Dv ARG_MAX
1.8 deraadt 243: - 4096.
1.1 deraadt 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
1.7 aaron 249: .Nm
1.1 deraadt 250: to terminate immediately if a command line containing
251: .Ar number
1.12 millert 252: arguments will not fit in the specified (or default) command line length.
1.1 deraadt 253: .El
254: .Pp
255: If no
256: .Ar utility
257: is specified,
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
1.7 aaron 266: .Nm
1.1 deraadt 267: utility exits immediately (without processing any further input) if a
268: command line cannot be assembled,
269: .Ar utility
1.12 millert 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 DIAGNOSTICS
1.7 aaron 277: .Nm
1.1 deraadt 278: exits with one of the following values:
1.6 aaron 279: .Pp
1.1 deraadt 280: .Bl -tag -width Ds -compact
281: .It 0
282: All invocations of
283: .Ar utility
284: returned a zero exit status.
285: .It 123
286: One or more invocations of
287: .Ar utility
288: returned a nonzero exit status.
289: .It 124
290: The
291: .Ar utility
292: exited with a 255 exit status.
293: .It 125
294: The
295: .Ar utility
296: was killed or stopped by a signal.
297: .It 126
298: The
299: .Ar utility
1.12 millert 300: was found but could not be executed.
1.1 deraadt 301: .It 127
302: The
303: .Ar utility
304: could not be found.
305: .It 1
306: Some other error occurred.
307: .El
308: .Sh SEE ALSO
309: .Xr echo 1 ,
1.12 millert 310: .Xr find 1 ,
311: .Xr execvp 3
1.1 deraadt 312: .Sh STANDARDS
313: The
1.7 aaron 314: .Nm
1.1 deraadt 315: utility is expected to be
316: .St -p1003.2
317: compliant.
1.12 millert 318: The
1.17 ! otto 319: .Fl 0 , J , o , P ,
! 320: .Fl R ,
1.12 millert 321: and
1.14 brad 322: .Fl r
1.12 millert 323: options are non-standard
324: extensions which may not be available on other operating systems.
325: .Pp
326: The meanings of the 123, 124, and 125 exit values were taken from
327: .Tn GNU
328: .Nm xargs .
1.1 deraadt 329: .Sh HISTORY
1.12 millert 330: The
331: .Nm
332: command appeared in PWB UNIX.
333: .Sh BUGS
334: If
335: .Ar utility
336: attempts to invoke another command such that the number of arguments or the
337: size of the environment is increased, it risks
338: .Xr execvp 3
339: failing with
340: .Er E2BIG .