Annotation of src/usr.bin/xargs/xargs.1, Revision 1.1.1.1
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
48: .Op Fl t
49: .Oo Op Fl x
50: .Fl n Ar number
51: .Oc
52: .Op Fl s Ar size
53: .Op Ar utility Op Ar arguments ...
54: .Sh DESCRIPTION
55: The
56: .Nm xargs
57: utility reads space, tab, newline and end-of-file delimited arguments
58: from the standard input and executes the specified
59: .Ar utility
60: with them as
61: arguments.
62: .Pp
63: The utility and any arguments specified on the command line are given
64: to the
65: .Ar utility
66: upon each invocation, followed by some number of the arguments read
67: from standard input.
68: The
69: .Ar utility
70: is repeatedly executed until standard input is exhausted.
71: .Pp
72: Spaces, tabs and newlines may be embedded in arguments using single
73: (``\ '\ '')
74: .Ek
75: or double (``"'') quotes or backslashes (``\e'').
76: Single quotes escape all non-single quote characters, excluding newlines,
77: up to the matching single quote.
78: Double quotes escape all non-double quote characters, excluding newlines,
79: up to the matching double quote.
80: Any single character, including newlines, may be escaped by a backslash.
81: .Pp
82: The options are as follows:
83: .Bl -tag -width indent
84: .It Fl n Ar number
85: Set the maximum number of arguments taken from standard input for each
86: invocation of the utility.
87: An invocation of
88: .Ar utility
89: will use less than
90: .Ar number
91: standard input arguments if the number of bytes accumulated (see the
92: .Fl s
93: option) exceeds the specified
94: .Ar size
95: or there are fewer than
96: .Ar number
97: arguments remaining for the last invocation of
98: .Ar utility .
99: The current default value for
100: .Ar number
101: is 5000.
102: .It Fl s Ar size
103: Set the maximum number of bytes for the command line length provided to
104: .Ar utility .
105: The sum of the length of the utility name and the arguments passed to
106: .Ar utility
107: (including
108: .Dv NULL
109: terminators) will be less than or equal to this number.
110: The current default value for
111: .Ar size
112: is
113: .Dv ARG_MAX
114: - 2048.
115: .It Fl t
116: Echo the command to be executed to standard error immediately before it
117: is executed.
118: .It Fl x
119: Force
120: .Nm xargs
121: to terminate immediately if a command line containing
122: .Ar number
123: arguments will not fit in the specified (or default) command line length.
124: .El
125: .Pp
126: If no
127: .Ar utility
128: is specified,
129: .Xr echo 1
130: is used.
131: .Pp
132: Undefined behavior may occur if
133: .Ar utility
134: reads from the standard input.
135: .Pp
136: The
137: .Nm xargs
138: utility exits immediately (without processing any further input) if a
139: command line cannot be assembled,
140: .Ar utility
141: cannot be invoked, an invocation of the utility is terminated by a signal
142: or an invocation of the utility exits with a value of 255.
143: .Sh DIAGNOSTICS
144: .Nm xargs
145: exits with one of the following values:
146: .Bl -tag -width Ds -compact
147: .It 0
148: All invocations of
149: .Ar utility
150: returned a zero exit status.
151: .It 123
152: One or more invocations of
153: .Ar utility
154: returned a nonzero exit status.
155: .It 124
156: The
157: .Ar utility
158: exited with a 255 exit status.
159: .It 125
160: The
161: .Ar utility
162: was killed or stopped by a signal.
163: .It 126
164: The
165: .Ar utility
166: was found but could not be invoked.
167: .It 127
168: The
169: .Ar utility
170: could not be found.
171: .It 1
172: Some other error occurred.
173: .El
174: .Sh SEE ALSO
175: .Xr echo 1 ,
176: .Xr find 1
177: .Sh STANDARDS
178: The
179: .Nm xargs
180: utility is expected to be
181: .St -p1003.2
182: compliant.
183: .Sh HISTORY
184: 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