Annotation of src/usr.bin/xargs/xargs.1, Revision 1.13
1.13 ! jmc 1: .\" $OpenBSD: xargs.1,v 1.12 2003/06/12 01:09:23 millert 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.12 millert 46: .Op Fl 0opt
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.12 millert 58: .Op Fl P Ar maxjobs
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
77: is repeatedly executed until standard input is exhausted.
78: .Pp
79: Spaces, tabs and newlines may be embedded in arguments using single
1.7 aaron 80: .Pq Ql '
81: or double
82: .Pq Ql \&"
83: quotes or backslashes
84: .Pq Ql \e .
1.1 deraadt 85: Single quotes escape all non-single quote characters, excluding newlines,
86: up to the matching single quote.
87: Double quotes escape all non-double quote characters, excluding newlines,
88: up to the matching double quote.
89: Any single character, including newlines, may be escaped by a backslash.
90: .Pp
91: The options are as follows:
1.10 aaron 92: .Bl -tag -width Ds
1.2 deraadt 93: .It Fl 0
1.12 millert 94: Change
1.7 aaron 95: .Nm
1.2 deraadt 96: to expect NUL
1.7 aaron 97: .Pq Ql \e0
1.5 deraadt 98: characters as separators, instead of spaces and newlines.
1.2 deraadt 99: This is expected to be used in concert with the
1.3 deraadt 100: .Fl print0
101: function in
1.7 aaron 102: .Xr find 1 .
1.12 millert 103: .It Fl E Ar eofstr
104: Use
105: .Ar eofstr
106: as a logical EOF marker.
107: .It Fl I Ar replstr
108: Execute
109: .Ar utility
110: for each input line, replacing one or more occurrences of
111: .Ar replstr
112: in up to
113: .Ar replacements
114: (or 5 if no
115: .Fl R
116: flag is specified) arguments to
117: .Ar utility
118: with the entire line of input.
119: The resulting arguments, after replacement is done, will not be allowed to grow
120: beyond 255 bytes; this is implemented by concatenating as much of the argument
121: containing
122: .Ar replstr
123: as possible, to the constructed arguments to
124: .Ar utility ,
125: up to 255 bytes.
126: The 255 byte limit does not apply to arguments to
127: .Ar utility
128: which do not contain
129: .Ar replstr ,
130: and furthermore, no replacement will be done on
131: .Ar utility
132: itself.
133: Implies
134: .Fl x .
135: .It Fl J Ar replstr
136: If this option is specified,
137: .Nm
138: will use the data read from standard input to replace the first occurrence of
139: .Ar replstr
140: instead of appending that data after all other arguments.
141: This option will not effect how many arguments will be read from input
142: .Pq Fl n ,
143: or the size of the command(s)
144: .Nm
145: will generate
146: .Pq Fl s .
147: The option just moves where those arguments will be placed in the command(s)
148: that are executed.
149: The
150: .Ar replstr
151: must show up as a distinct
152: .Ar argument
153: to
154: .Nm xargs .
155: It will not be recognized if, for instance, it is in the middle of a
156: quoted string.
157: Furthermore, only the first occurrence of the
158: .Ar replstr
159: will be replaced.
160: For example, the following command will copy the list of files and
161: directories which start with an uppercase letter in the current
162: directory to
163: .Pa destdir :
164: .Pp
1.13 ! jmc 165: .Dl "/bin/ls -1d [A-Z]* | xargs -J % cp -rp % destdir"
1.12 millert 166: .It Fl L Ar number
167: Call
168: .Ar utility
169: for every
170: .Ar number
171: of lines read.
172: If EOF is reached and fewer than
173: .Ar number
174: lines have been read then
175: .Ar utility
176: will be called with the available lines.
1.1 deraadt 177: .It Fl n Ar number
178: Set the maximum number of arguments taken from standard input for each
1.12 millert 179: invocation of
180: .Ar utility .
1.1 deraadt 181: An invocation of
182: .Ar utility
183: will use less than
184: .Ar number
185: standard input arguments if the number of bytes accumulated (see the
186: .Fl s
187: option) exceeds the specified
188: .Ar size
189: or there are fewer than
190: .Ar number
191: arguments remaining for the last invocation of
192: .Ar utility .
193: The current default value for
194: .Ar number
195: is 5000.
1.12 millert 196: .It Fl o
197: Reopen stdin as
198: .Pa /dev/tty
199: in the child process before executing the command.
200: This is useful if you want
201: .Nm
202: to run an interactive application.
203: .It Fl P Ar maxprocs
204: Parallel mode: run at most
205: .Ar maxprocs
206: invocations of
207: .Ar utility
208: at once.
209: .It Fl p
210: Echo each command to be executed and ask the user whether it should be
211: executed.
212: An affirmative response,
213: .Ql y
214: in the POSIX locale,
215: causes the command to be executed, any other response causes it to be
216: skipped.
217: No commands are executed if the process is not attached to a terminal.
218: .It Fl R Ar replacements
219: Specify the maximum number of arguments that
220: .Fl I
221: will do replacement in.
222: If
223: .Ar replacements
224: is negative, the number of arguments in which to replace is unbounded.
1.1 deraadt 225: .It Fl s Ar size
1.12 millert 226: Set the maximum number of bytes for the command line length provided to
1.1 deraadt 227: .Ar utility .
1.12 millert 228: The sum of the length of the utility name, the arguments passed to
1.1 deraadt 229: .Ar utility
1.12 millert 230: (including
231: .Dv NUL
232: terminators) and the current environment will be less than or equal to
233: this number.
1.1 deraadt 234: The current default value for
235: .Ar size
236: is
237: .Dv ARG_MAX
1.8 deraadt 238: - 4096.
1.1 deraadt 239: .It Fl t
240: Echo the command to be executed to standard error immediately before it
241: is executed.
242: .It Fl x
243: Force
1.7 aaron 244: .Nm
1.1 deraadt 245: to terminate immediately if a command line containing
246: .Ar number
1.12 millert 247: arguments will not fit in the specified (or default) command line length.
1.1 deraadt 248: .El
249: .Pp
250: If no
251: .Ar utility
252: is specified,
253: .Xr echo 1
254: is used.
255: .Pp
256: Undefined behavior may occur if
257: .Ar utility
258: reads from the standard input.
259: .Pp
260: The
1.7 aaron 261: .Nm
1.1 deraadt 262: utility exits immediately (without processing any further input) if a
263: command line cannot be assembled,
264: .Ar utility
1.12 millert 265: cannot be invoked, an invocation of
266: .Ar utility
267: is terminated by a signal,
268: or an invocation of
269: .Ar utility
270: exits with a value of 255.
271: .Sh DIAGNOSTICS
1.7 aaron 272: .Nm
1.1 deraadt 273: exits with one of the following values:
1.6 aaron 274: .Pp
1.1 deraadt 275: .Bl -tag -width Ds -compact
276: .It 0
277: All invocations of
278: .Ar utility
279: returned a zero exit status.
280: .It 123
281: One or more invocations of
282: .Ar utility
283: returned a nonzero exit status.
284: .It 124
285: The
286: .Ar utility
287: exited with a 255 exit status.
288: .It 125
289: The
290: .Ar utility
291: was killed or stopped by a signal.
292: .It 126
293: The
294: .Ar utility
1.12 millert 295: was found but could not be executed.
1.1 deraadt 296: .It 127
297: The
298: .Ar utility
299: could not be found.
300: .It 1
301: Some other error occurred.
302: .El
303: .Sh SEE ALSO
304: .Xr echo 1 ,
1.12 millert 305: .Xr find 1 ,
306: .Xr execvp 3
1.1 deraadt 307: .Sh STANDARDS
308: The
1.7 aaron 309: .Nm
1.1 deraadt 310: utility is expected to be
311: .St -p1003.2
312: compliant.
1.12 millert 313: The
314: .Fl J , o , P
315: and
316: .Fl R
317: options are non-standard
318: extensions which may not be available on other operating systems.
319: .Pp
320: The meanings of the 123, 124, and 125 exit values were taken from
321: .Tn GNU
322: .Nm xargs .
1.1 deraadt 323: .Sh HISTORY
1.12 millert 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 .
![[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