Annotation of src/usr.bin/xargs/xargs.1, Revision 1.26
1.26 ! jmc 1: .\" $OpenBSD: xargs.1,v 1.25 2010/03/25 01:03:57 schwarze 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.26 ! jmc 37: .Dd $Mdocdate: March 25 2010 $
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.19 jmc 100: The quoting mechanisms described above are not performed.
101: This option is expected to be used in concert with the
1.3 deraadt 102: .Fl print0
103: function in
1.7 aaron 104: .Xr find 1 .
1.12 millert 105: .It Fl E Ar eofstr
106: Use
107: .Ar eofstr
108: as a logical EOF marker.
109: .It Fl I Ar replstr
110: Execute
111: .Ar utility
112: for each input line, replacing one or more occurrences of
113: .Ar replstr
114: in up to
115: .Ar replacements
116: (or 5 if no
117: .Fl R
118: flag is specified) arguments to
119: .Ar utility
120: with the entire line of input.
121: The resulting arguments, after replacement is done, will not be allowed to grow
122: beyond 255 bytes; this is implemented by concatenating as much of the argument
123: containing
124: .Ar replstr
125: as possible, to the constructed arguments to
126: .Ar utility ,
127: up to 255 bytes.
128: The 255 byte limit does not apply to arguments to
129: .Ar utility
130: which do not contain
131: .Ar replstr ,
132: and furthermore, no replacement will be done on
133: .Ar utility
134: itself.
135: Implies
136: .Fl x .
137: .It Fl J Ar replstr
138: If this option is specified,
139: .Nm
140: will use the data read from standard input to replace the first occurrence of
141: .Ar replstr
142: instead of appending that data after all other arguments.
143: This option will not effect how many arguments will be read from input
144: .Pq Fl n ,
145: or the size of the command(s)
146: .Nm
147: will generate
148: .Pq Fl s .
149: The option just moves where those arguments will be placed in the command(s)
150: that are executed.
151: The
152: .Ar replstr
153: must show up as a distinct
154: .Ar argument
155: to
156: .Nm xargs .
157: It will not be recognized if, for instance, it is in the middle of a
158: quoted string.
159: Furthermore, only the first occurrence of the
160: .Ar replstr
161: will be replaced.
162: For example, the following command will copy the list of files and
163: directories which start with an uppercase letter in the current
164: directory to
165: .Pa destdir :
166: .Pp
1.18 bernd 167: .Dl "/bin/ls -1d [A-Z]* | xargs -J % cp -Rp % destdir"
1.12 millert 168: .It Fl L Ar number
169: Call
170: .Ar utility
171: for every
172: .Ar number
1.25 schwarze 173: of non-empty lines read.
174: A line ending in unescaped white space and the next non-empty line
175: are considered to form one single line.
1.12 millert 176: If EOF is reached and fewer than
177: .Ar number
178: lines have been read then
179: .Ar utility
180: will be called with the available lines.
1.1 deraadt 181: .It Fl n Ar number
182: Set the maximum number of arguments taken from standard input for each
1.12 millert 183: invocation of
184: .Ar utility .
1.1 deraadt 185: An invocation of
186: .Ar utility
187: will use less than
188: .Ar number
189: standard input arguments if the number of bytes accumulated (see the
190: .Fl s
191: option) exceeds the specified
192: .Ar size
193: or there are fewer than
194: .Ar number
195: arguments remaining for the last invocation of
196: .Ar utility .
197: The current default value for
198: .Ar number
199: is 5000.
1.12 millert 200: .It Fl o
201: Reopen stdin as
202: .Pa /dev/tty
203: in the child process before executing the command.
204: This is useful if you want
205: .Nm
206: to run an interactive application.
207: .It Fl P Ar maxprocs
208: Parallel mode: run at most
209: .Ar maxprocs
210: invocations of
211: .Ar utility
212: at once.
213: .It Fl p
214: Echo each command to be executed and ask the user whether it should be
215: executed.
216: An affirmative response,
217: .Ql y
218: in the POSIX locale,
219: causes the command to be executed, any other response causes it to be
220: skipped.
221: No commands are executed if the process is not attached to a terminal.
222: .It Fl R Ar replacements
223: Specify the maximum number of arguments that
224: .Fl I
225: will do replacement in.
226: If
227: .Ar replacements
228: is negative, the number of arguments in which to replace is unbounded.
1.14 brad 229: .It Fl r
230: Do not run the command if there are no arguments.
231: Normally the command is executed at least once
232: even if there are no arguments.
1.1 deraadt 233: .It Fl s Ar size
1.12 millert 234: Set the maximum number of bytes for the command line length provided to
1.1 deraadt 235: .Ar utility .
1.12 millert 236: The sum of the length of the utility name, the arguments passed to
1.1 deraadt 237: .Ar utility
1.12 millert 238: (including
239: .Dv NUL
240: terminators) and the current environment will be less than or equal to
241: this number.
1.1 deraadt 242: The current default value for
243: .Ar size
244: is
245: .Dv ARG_MAX
1.8 deraadt 246: - 4096.
1.1 deraadt 247: .It Fl t
248: Echo the command to be executed to standard error immediately before it
249: is executed.
250: .It Fl x
251: Force
1.7 aaron 252: .Nm
1.1 deraadt 253: to terminate immediately if a command line containing
254: .Ar number
1.12 millert 255: arguments will not fit in the specified (or default) command line length.
1.1 deraadt 256: .El
257: .Pp
258: If no
259: .Ar utility
260: is specified,
261: .Xr echo 1
262: is used.
263: .Pp
264: Undefined behavior may occur if
265: .Ar utility
266: reads from the standard input.
267: .Pp
268: The
1.7 aaron 269: .Nm
1.1 deraadt 270: utility exits immediately (without processing any further input) if a
271: command line cannot be assembled,
272: .Ar utility
1.12 millert 273: cannot be invoked, an invocation of
274: .Ar utility
275: is terminated by a signal,
276: or an invocation of
277: .Ar utility
278: exits with a value of 255.
1.26 ! jmc 279: .Sh EXIT STATUS
1.7 aaron 280: .Nm
1.1 deraadt 281: exits with one of the following values:
1.6 aaron 282: .Pp
1.26 ! jmc 283: .Bl -tag -width Ds -offset indent -compact
1.1 deraadt 284: .It 0
285: All invocations of
286: .Ar utility
287: returned a zero exit status.
288: .It 123
289: One or more invocations of
290: .Ar utility
291: returned a nonzero exit status.
292: .It 124
293: The
294: .Ar utility
295: exited with a 255 exit status.
296: .It 125
297: The
298: .Ar utility
299: was killed or stopped by a signal.
300: .It 126
301: The
302: .Ar utility
1.12 millert 303: was found but could not be executed.
1.1 deraadt 304: .It 127
305: The
306: .Ar utility
307: could not be found.
308: .It 1
309: Some other error occurred.
310: .El
311: .Sh SEE ALSO
312: .Xr echo 1 ,
1.12 millert 313: .Xr find 1 ,
314: .Xr execvp 3
1.1 deraadt 315: .Sh STANDARDS
316: The
1.7 aaron 317: .Nm
1.20 jmc 318: utility is compliant with the
1.22 jmc 319: .St -p1003.1-2008
1.20 jmc 320: specification.
321: .Pp
322: The flags
1.24 schwarze 323: .Fl I
324: and
325: .Fl L
326: are compliant with the
327: .St -xpg4
328: specification.
329: .Pp
330: The flags
1.20 jmc 331: .Op Fl 0JoPRr
1.24 schwarze 332: are extensions to those specifications.
1.12 millert 333: .Pp
334: The meanings of the 123, 124, and 125 exit values were taken from
335: .Tn GNU
336: .Nm xargs .
1.1 deraadt 337: .Sh HISTORY
1.12 millert 338: The
339: .Nm
1.23 sobrado 340: command appeared in PWB
341: .Ux .
1.12 millert 342: .Sh BUGS
343: If
344: .Ar utility
345: attempts to invoke another command such that the number of arguments or the
346: size of the environment is increased, it risks
347: .Xr execvp 3
348: failing with
349: .Er E2BIG .
![[BACK]](/icons/back.gif){kind=icon}
Return to xargs.1 CVS log ![[TXT]](/icons/text.gif){kind=icon}
![[DIR]](/icons/dir.gif){kind=icon}
Up to [local] / src / usr.bin / xargs