Annotation of src/usr.bin/xargs/xargs.1, Revision 1.3
1.1 deraadt 1: .\" $NetBSD: xargs.1,v 1.6 1994/11/14 06:51:40 jtc Exp $
2: .\"
3: .\" Copyright (c) 1990, 1991, 1993
4: .\" The Regents of the University of California. All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to Berkeley by
7: .\" John B. Roll Jr. and the Institute of Electrical and Electronics
8: .\" Engineers, Inc.
9: .\"
10: .\" Redistribution and use in source and binary forms, with or without
11: .\" modification, are permitted provided that the following conditions
12: .\" are met:
13: .\" 1. Redistributions of source code must retain the above copyright
14: .\" notice, this list of conditions and the following disclaimer.
15: .\" 2. Redistributions in binary form must reproduce the above copyright
16: .\" notice, this list of conditions and the following disclaimer in the
17: .\" documentation and/or other materials provided with the distribution.
18: .\" 3. All advertising materials mentioning features or use of this software
19: .\" must display the following acknowledgement:
20: .\" This product includes software developed by the University of
21: .\" California, Berkeley and its contributors.
22: .\" 4. Neither the name of the University nor the names of its contributors
23: .\" may be used to endorse or promote products derived from this software
24: .\" without specific prior written permission.
25: .\"
26: .\" THIS SOFTWARE IS PROVIDED BY THE REGENTS AND CONTRIBUTORS ``AS IS'' AND
27: .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
28: .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
29: .\" ARE DISCLAIMED. IN NO EVENT SHALL THE REGENTS OR CONTRIBUTORS BE LIABLE
30: .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
31: .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
32: .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
33: .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
34: .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
35: .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
36: .\" SUCH DAMAGE.
37: .\"
38: .\" @(#)xargs.1 8.1 (Berkeley) 6/6/93
39: .\"
40: .Dd June 6, 1993
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 xargs
1.2 deraadt 48: .Op Fl 0
1.1 deraadt 49: .Op Fl t
50: .Oo Op Fl x
51: .Fl n Ar number
52: .Oc
53: .Op Fl s Ar size
54: .Op Ar utility Op Ar arguments ...
55: .Sh DESCRIPTION
56: The
57: .Nm xargs
58: utility reads space, tab, newline and end-of-file delimited arguments
59: from the standard input and executes the specified
60: .Ar utility
61: with them as
62: arguments.
63: .Pp
64: The utility and any arguments specified on the command line are given
65: to the
66: .Ar utility
67: upon each invocation, followed by some number of the arguments read
68: from standard input.
69: The
70: .Ar utility
71: is repeatedly executed until standard input is exhausted.
72: .Pp
73: Spaces, tabs and newlines may be embedded in arguments using single
74: (``\ '\ '')
75: .Ek
76: or double (``"'') quotes or backslashes (``\e'').
77: Single quotes escape all non-single quote characters, excluding newlines,
78: up to the matching single quote.
79: Double quotes escape all non-double quote characters, excluding newlines,
80: up to the matching double quote.
81: Any single character, including newlines, may be escaped by a backslash.
82: .Pp
83: The options are as follows:
84: .Bl -tag -width indent
1.2 deraadt 85: .It Fl 0
86: Changes
87: .Nm xargs
88: to expect NUL
89: (``\\0'')
90: characters as seperators, instead of spaces and newlines.
91: This is expected to be used in concert with the
1.3 ! deraadt 92: .Fl print0
! 93: function in
1.2 deraadt 94: .Nm find .
1.1 deraadt 95: .It Fl n Ar number
96: Set the maximum number of arguments taken from standard input for each
97: invocation of the utility.
98: An invocation of
99: .Ar utility
100: will use less than
101: .Ar number
102: standard input arguments if the number of bytes accumulated (see the
103: .Fl s
104: option) exceeds the specified
105: .Ar size
106: or there are fewer than
107: .Ar number
108: arguments remaining for the last invocation of
109: .Ar utility .
110: The current default value for
111: .Ar number
112: is 5000.
113: .It Fl s Ar size
114: Set the maximum number of bytes for the command line length provided to
115: .Ar utility .
116: The sum of the length of the utility name and the arguments passed to
117: .Ar utility
118: (including
119: .Dv NULL
120: terminators) will be less than or equal to this number.
121: The current default value for
122: .Ar size
123: is
124: .Dv ARG_MAX
125: - 2048.
126: .It Fl t
127: Echo the command to be executed to standard error immediately before it
128: is executed.
129: .It Fl x
130: Force
131: .Nm xargs
132: to terminate immediately if a command line containing
133: .Ar number
134: arguments will not fit in the specified (or default) command line length.
135: .El
136: .Pp
137: If no
138: .Ar utility
139: is specified,
140: .Xr echo 1
141: is used.
142: .Pp
143: Undefined behavior may occur if
144: .Ar utility
145: reads from the standard input.
146: .Pp
147: The
148: .Nm xargs
149: utility exits immediately (without processing any further input) if a
150: command line cannot be assembled,
151: .Ar utility
152: cannot be invoked, an invocation of the utility is terminated by a signal
153: or an invocation of the utility exits with a value of 255.
154: .Sh DIAGNOSTICS
155: .Nm xargs
156: exits with one of the following values:
157: .Bl -tag -width Ds -compact
158: .It 0
159: All invocations of
160: .Ar utility
161: returned a zero exit status.
162: .It 123
163: One or more invocations of
164: .Ar utility
165: returned a nonzero exit status.
166: .It 124
167: The
168: .Ar utility
169: exited with a 255 exit status.
170: .It 125
171: The
172: .Ar utility
173: was killed or stopped by a signal.
174: .It 126
175: The
176: .Ar utility
177: was found but could not be invoked.
178: .It 127
179: The
180: .Ar utility
181: could not be found.
182: .It 1
183: Some other error occurred.
184: .El
185: .Sh SEE ALSO
186: .Xr echo 1 ,
187: .Xr find 1
188: .Sh STANDARDS
189: The
190: .Nm xargs
191: utility is expected to be
192: .St -p1003.2
193: compliant.
194: .Sh HISTORY
195: The meaning of 123, 124, and 125 exit values were taken from GNU xargs.
![[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