Annotation of src/usr.bin/xargs/xargs.1, Revision 1.20
1.20 ! jmc 1: .\" $OpenBSD: xargs.1,v 1.19 2006/08/12 07:10:56 jmc 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.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
173: of lines read.
174: If EOF is reached and fewer than
175: .Ar number
176: lines have been read then
177: .Ar utility
178: will be called with the available lines.
1.1 deraadt 179: .It Fl n Ar number
180: Set the maximum number of arguments taken from standard input for each
1.12 millert 181: invocation of
182: .Ar utility .
1.1 deraadt 183: An invocation of
184: .Ar utility
185: will use less than
186: .Ar number
187: standard input arguments if the number of bytes accumulated (see the
188: .Fl s
189: option) exceeds the specified
190: .Ar size
191: or there are fewer than
192: .Ar number
193: arguments remaining for the last invocation of
194: .Ar utility .
195: The current default value for
196: .Ar number
197: is 5000.
1.12 millert 198: .It Fl o
199: Reopen stdin as
200: .Pa /dev/tty
201: in the child process before executing the command.
202: This is useful if you want
203: .Nm
204: to run an interactive application.
205: .It Fl P Ar maxprocs
206: Parallel mode: run at most
207: .Ar maxprocs
208: invocations of
209: .Ar utility
210: at once.
211: .It Fl p
212: Echo each command to be executed and ask the user whether it should be
213: executed.
214: An affirmative response,
215: .Ql y
216: in the POSIX locale,
217: causes the command to be executed, any other response causes it to be
218: skipped.
219: No commands are executed if the process is not attached to a terminal.
220: .It Fl R Ar replacements
221: Specify the maximum number of arguments that
222: .Fl I
223: will do replacement in.
224: If
225: .Ar replacements
226: is negative, the number of arguments in which to replace is unbounded.
1.14 brad 227: .It Fl r
228: Do not run the command if there are no arguments.
229: Normally the command is executed at least once
230: even if there are no arguments.
1.1 deraadt 231: .It Fl s Ar size
1.12 millert 232: Set the maximum number of bytes for the command line length provided to
1.1 deraadt 233: .Ar utility .
1.12 millert 234: The sum of the length of the utility name, the arguments passed to
1.1 deraadt 235: .Ar utility
1.12 millert 236: (including
237: .Dv NUL
238: terminators) and the current environment will be less than or equal to
239: this number.
1.1 deraadt 240: The current default value for
241: .Ar size
242: is
243: .Dv ARG_MAX
1.8 deraadt 244: - 4096.
1.1 deraadt 245: .It Fl t
246: Echo the command to be executed to standard error immediately before it
247: is executed.
248: .It Fl x
249: Force
1.7 aaron 250: .Nm
1.1 deraadt 251: to terminate immediately if a command line containing
252: .Ar number
1.12 millert 253: arguments will not fit in the specified (or default) command line length.
1.1 deraadt 254: .El
255: .Pp
256: If no
257: .Ar utility
258: is specified,
259: .Xr echo 1
260: is used.
261: .Pp
262: Undefined behavior may occur if
263: .Ar utility
264: reads from the standard input.
265: .Pp
266: The
1.7 aaron 267: .Nm
1.1 deraadt 268: utility exits immediately (without processing any further input) if a
269: command line cannot be assembled,
270: .Ar utility
1.12 millert 271: cannot be invoked, an invocation of
272: .Ar utility
273: is terminated by a signal,
274: or an invocation of
275: .Ar utility
276: exits with a value of 255.
277: .Sh DIAGNOSTICS
1.7 aaron 278: .Nm
1.1 deraadt 279: exits with one of the following values:
1.6 aaron 280: .Pp
1.1 deraadt 281: .Bl -tag -width Ds -compact
282: .It 0
283: All invocations of
284: .Ar utility
285: returned a zero exit status.
286: .It 123
287: One or more invocations of
288: .Ar utility
289: returned a nonzero exit status.
290: .It 124
291: The
292: .Ar utility
293: exited with a 255 exit status.
294: .It 125
295: The
296: .Ar utility
297: was killed or stopped by a signal.
298: .It 126
299: The
300: .Ar utility
1.12 millert 301: was found but could not be executed.
1.1 deraadt 302: .It 127
303: The
304: .Ar utility
305: could not be found.
306: .It 1
307: Some other error occurred.
308: .El
309: .Sh SEE ALSO
310: .Xr echo 1 ,
1.12 millert 311: .Xr find 1 ,
312: .Xr execvp 3
1.1 deraadt 313: .Sh STANDARDS
314: The
1.7 aaron 315: .Nm
1.20 ! jmc 316: utility is compliant with the
! 317: .St -p1003.1-2004
! 318: specification.
! 319: .Pp
! 320: The flags
! 321: .Op Fl 0JoPRr
! 322: are extensions to that specification.
1.12 millert 323: .Pp
324: The meanings of the 123, 124, and 125 exit values were taken from
325: .Tn GNU
326: .Nm xargs .
1.1 deraadt 327: .Sh HISTORY
1.12 millert 328: The
329: .Nm
330: command appeared in PWB UNIX.
331: .Sh BUGS
332: If
333: .Ar utility
334: attempts to invoke another command such that the number of arguments or the
335: size of the environment is increased, it risks
336: .Xr execvp 3
337: failing with
338: .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