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