1xargs(1)                         User Commands                        xargs(1)
2
3
4

NAME

6       xargs - construct argument lists and invoke utility
7

SYNOPSIS

9       xargs [-t] [-p] [-e[eofstr]] [-E eofstr]
10            [-I replstr] [-i[replstr]] [-L number] [-l[number]]
11            [-n number [-x]] [-s size] [utility [argument...]]
12
13

DESCRIPTION

15       The  xargs  utility constructs a command line consisting of the utility
16       and argument operands specified followed by as many arguments  read  in
17       sequence  from  standard  input as fit in length and number constraints
18       specified by the options. The  xargs  utility  then  invokes  the  con‐
19       structed  command  line  and waits for its completion. This sequence is
20       repeated until an end-of-file condition is detected on  standard  input
21       or  an  invocation of a constructed command line returns an exit status
22       of 255.
23
24
25       Arguments in the standard input must be  separated  by  unquoted  blank
26       characters,  or  unescaped  blank  characters  or newline characters. A
27       string of zero or more non-double-quote (") and non-newline  characters
28       can  be  quoted by enclosing them in double-quotes. A string of zero or
29       more non-apostrophe (') and non-newline characters  can  be  quoted  by
30       enclosing them in apostrophes. Any unquoted character can be escaped by
31       preceding it with a backslash (\). The utility are executed one or more
32       times  until the end-of-file is reached. The results are unspecified if
33       the utility named by utility attempts to read from its standard input.
34
35
36       The generated command line length is the sum of the size  in  bytes  of
37       the utility name and each argument treated as strings, including a null
38       byte terminator for each of these strings. The xargs utility limits the
39       command  line  length  such  that when the command line is invoked, the
40       combined argument and environment lists can not  exceed  {ARG_MAX}−2048
41       bytes.  Within  this constraint, if neither the -n nor the -s option is
42       specified, the default command line length is at least {LINE_MAX}.
43

OPTIONS

45       The following options are supported:
46
47       -e[eofstr]     Uses eofstr as the logical  end-of-file  string.  Under‐
48                      score  (_) is assumed for the logical EOF string if nei‐
49                      ther -e nor -E is used. When the eofstr  option-argument
50                      is  omitted,  the  logical EOF string capability is dis‐
51                      abled and underscores are  taken  literally.  The  xargs
52                      utility reads standard input until either end-of-file or
53                      the logical EOF string is encountered.
54
55
56       -E eofstr      Specifies a logical end-of-file string  to  replace  the
57                      default  underscore.  xargs  reads  standard input until
58                      either end-of-file or the logical EOF string is  encoun‐
59                      tered. When eofstr is a null string, the logical end-of-
60                      file string capability is disabled and underscore  char‐
61                      acters are taken literally.
62
63
64       -I replstr     Insert  mode.  utility  is  executed  for each line from
65                      standard input, taking the entire line as a single argu‐
66                      ment,  inserting it in argument s for each occurrence of
67                      replstr. A maximum of five arguments  in  arguments  can
68                      each contain one or more instances of replstr. Any blank
69                      characters at the beginning of each  line  are  ignored.
70                      Constructed arguments cannot grow larger than 255 bytes.
71                      Option -x is forced on. The -I and -i options are  mutu‐
72                      ally exclusive; the last one specified takes effect.
73
74
75       -i[replstr]    This  option  is equivalent to -I replstr. The string {}
76                      is assumed for replstr if the option-argument  is  omit‐
77                      ted.
78
79
80       -L number      The  utility is executed for each non-empty number lines
81                      of arguments from standard input. The last invocation of
82                      utility  is  with fewer lines of arguments if fewer than
83                      number remain. A line is  considered  to  end  with  the
84                      first newline character unless the last character of the
85                      line is a blank character; a  trailing  blank  character
86                      signals  continuation to the next non-empty line, inclu‐
87                      sive. The -L, -l, and -n options are mutually exclusive;
88                      the last one specified takes effect.
89
90
91       -l[number]     (The  letter  ell.) This option is equivalent to -L num‐
92                      ber. If number is omitted, 1 is assumed.  Option  -x  is
93                      forced on.
94
95
96       -n number      Invokes  utility  using as many standard input arguments
97                      as possible, up to number (a positive  decimal  integer)
98                      arguments maximum. Fewer arguments are used if:
99
100                          o      The  command  line length accumulated exceeds
101                                 the size  specified  by  the  -s  option  (or
102                                 {LINE_MAX} if there is no -s option), or
103
104                          o      The last iteration has fewer than number, but
105                                 not zero, operands remaining.
106
107
108       -p             Prompt mode. The user is asked whether to execute  util‐
109                      ity  at each invocation. Trace mode (-t) is turned on to
110                      write the command instance to be executed, followed by a
111                      prompt  to standard error. An affirmative response (spe‐
112                      cific to the user's locale) read from /dev/tty  executes
113                      the  command;  otherwise,  that particular invocation of
114                      utility is skipped.
115
116
117       -s size        Invokes utility using as many standard  input  arguments
118                      as  possible  yielding  a  command line length less than
119                      size (a positive decimal integer) bytes. Fewer arguments
120                      are used if:
121
122                          o      The  total  number  of arguments exceeds that
123                                 specified by the -n option, or
124
125                          o      The total number of lines exceeds that speci‐
126                                 fied by the -L option, or
127
128                          o      End  of file is encountered on standard input
129                                 before size bytes are accumulated.
130                      Values of size up to at least {LINE_MAX} bytes are  sup‐
131                      ported,  provided  that  the  constraints  specified  in
132                      DESCRIPTION are met. It is not considered an error if  a
133                      value  larger  than that supported by the implementation
134                      or exceeding the constraints specified in DESCRIPTION is
135                      specified.  xargs  uses  the  largest  value it supports
136                      within the constraints.
137
138
139       -t    Enables trace mode. Each generated command  line  is  written  to
140             standard error just prior to invocation.
141
142
143       -x    Terminates if a command line containing number arguments (see the
144             -n option above) or number lines (see the -L option  above)  does
145             not  fit  in  the  implied  or  specified size (see the -s option
146             above).
147
148

OPERANDS

150       The following operands are supported:
151
152       utility     The name of the utility to be invoked, found by search path
153                   using  the  PATH  environment variable. (ee environ(5).) If
154                   utility is omitted, the default is the echo(1) utility.  If
155                   the utility operand names any of the special built-in util‐
156                   ities in shell_builtins(1), the results are undefined.
157
158
159       argument    An initial option or operand for the invocation of utility.
160
161

USAGE

163       The 255 exit status allows a utility being used by xargs to tell  xargs
164       to  terminate if it knows no further invocations using the current data
165       stream succeeds. Thus, utility should explicitly exit with an appropri‐
166       ate value to avoid accidentally returning with 255.
167
168
169       Notice  that  input is parsed as lines. Blank characters separate argu‐
170       ments. If xargs is used to bundle output  of  commands  like  find  dir
171       -print  or  ls  into  commands  to  be executed, unexpected results are
172       likely if any filenames contain any blank characters or newline charac‐
173       ters.  This  can  be fixed by using find to call a script that converts
174       each file found into a quoted string  that  is  then  piped  to  xargs.
175       Notice  that the quoting rules used by xargs are not the same as in the
176       shell. They were not made consistent here because existing applications
177       depend  on the current rules and the shell syntax is not fully compati‐
178       ble with it. An easy rule that can be used to transform any string into
179       a  quoted form that xargs interprets correctly is to precede each char‐
180       acter in the string with a backslash (\).
181
182
183       On implementations with a large value for {ARG_MAX}, xargs can  produce
184       command lines longer than {LINE_MAX}. For invocation of utilities, this
185       is not a problem. If xargs is being used to create a text  file,  users
186       should  explicitly  set  the  maximum  command  line length with the -s
187       option.
188
189
190       The xargs utility returns exit status 127 if an error  occurs  so  that
191       applications  can distinguish "failure to find a utility" from "invoked
192       utility exited with an error indication."  The  value  127  was  chosen
193       because  it is not commonly used for other meanings; most utilities use
194       small values for "normal error conditions" and the values above 128 can
195       be  confused with termination due to receipt of a signal. The value 126
196       was chosen in a similar manner to indicate that the  utility  could  be
197       found, but not invoked.
198

EXAMPLES

200       Example 1 Using the xargs command
201
202
203       The  following  example  moves all files from directory $1 to directory
204       $2, and echo each move command just before doing it:
205
206
207         example% ls $1 | xargs -I {} -t mv $1/{} $2/{}
208
209
210
211
212       The following command combines the output of the parenthesised commands
213       onto one line, which is then written to the end of file log:
214
215
216         example% (logname; date; printf "%s\n" "$0 $*") | xargs >>log
217
218
219
220
221       The  following  command invokes diff with successive pairs of arguments
222       originally typed as command  line  arguments  (assuming  there  are  no
223       embedded  blank  characters  in  the  elements of the original argument
224       list):
225
226
227         example% printf "%s\n" "$*" | xargs -n 2 -x diff
228
229
230
231
232       The user is asked which files  in  the  current  directory  are  to  be
233       archived.  The  files  are archived into arch ; a, one at a time, or b,
234       many at a time:
235
236
237         example% ls | xargs -p -L 1 ar -r arch
238         ls | xargs -p -L 1 | xargs ar -r arch
239
240
241
242
243       The following executes with successive pairs  of  arguments  originally
244       typed as command line arguments:
245
246
247         example% echo $* | xargs -n 2 diff
248
249
250

ENVIRONMENT VARIABLES

252       See  environ(5) for descriptions of the following environment variables
253       that affect the execution of xargs: LANG, LC_ALL, LC_COLLATE, LC_CTYPE,
254       LC_MESSAGES, and NLSPATH.
255
256       PATH    Determine the location of utility.
257
258
259
260       Affirmative  responses are processed using the extended regular expres‐
261       sion defined for the yesexpr keyword in the LC_MESSAGES category of the
262       user's  locale. The locale specified in the LC_COLLATE category defines
263       the behavior of ranges, equivalence classes, and  multi-character  col‐
264       lating  elements used in the expression defined for yesexpr. The locale
265       specified in LC_CTYPE  determines  the  locale  for  interpretation  of
266       sequences of bytes of text data a characters, the behavior of character
267       classes used in the expression defined for the yesexpr. See locale(5).
268

EXIT STATUS

270       The following exit values are returned:
271
272       0           All invocations of utility returned exit status 0.
273
274
275       1−125       A command line meeting the specified requirements could not
276                   be  assembled,  one  or  more of the invocations of utility
277                   returned a  non-zero  exit  status,  or  some  other  error
278                   occurred.
279
280
281       126         The utility specified by utility was found but could not be
282                   invoked.
283
284
285       127         The utility specified by utility could not be found.
286
287
288
289       If a command line meeting the specified requirements cannot  be  assem‐
290       bled,  the  utility  cannot be invoked, an invocation of the utility is
291       terminated by a signal, or an invocation of the utility exits with exit
292       status  255,  the  xargs  utility  writes a diagnostic message and exit
293       without processing any remaining input.
294

ATTRIBUTES

296       See attributes(5) for descriptions of the following attributes:
297
298
299
300
301       ┌─────────────────────────────┬─────────────────────────────┐
302       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
303       ├─────────────────────────────┼─────────────────────────────┤
304       │Availability                 │SUNWcsu                      │
305       ├─────────────────────────────┼─────────────────────────────┤
306       │CSI                          │Enabled                      │
307       ├─────────────────────────────┼─────────────────────────────┤
308       │Interface Stability          │Standard                     │
309       └─────────────────────────────┴─────────────────────────────┘
310

SEE ALSO

312       echo(1), shell_builtins(1), attributes(5), environ(5), standards(5)
313
314
315
316SunOS 5.11                        17 Jul 2007                         xargs(1)
Impressum