'\"macro stdmacro
.if n .pH g1.xargs @(#)xargs	40.5 of 10/10/89
.\" Copyright 1989 AT&T
.nr X
.if \nX=0 .ds x} xargs 1 "User Environment Utilities" "\&"
.if \nX=1 .ds x} xargs 1 "User Environment Utilities"
.if \nX=2 .ds x} xargs 1 "" "\&"
.if \nX=3 .ds x} xargs "" "" "\&"
.TH \*(x}
.SH NAME
\f4xargs\f1 \- construct argument list(s) and execute command 
.SH SYNOPSIS
\f4xargs\f1
[
.I flags
] [
.I command
[
.I initial-arguments
] ]
.SH DESCRIPTION
\f4xargs\fP
combines the fixed
.I initial-arguments\^
with arguments read from standard input to execute the specified
.I command\^
one or more times.
The number of arguments read for each
.I command\^
invocation
and the manner in which they are combined
are determined by the flags specified.
.PP
.IR command ,
which may be a shell file,
is searched for, using one's \f4\s-1$PATH\s+1\fP.
If
.I command\^
is omitted,
\f4/usr/bin/echo\f1
is used.
.PP
Arguments read in from standard input are defined to be contiguous
strings of characters delimited by one or more blanks, tabs, or new-lines;
empty lines are always discarded.
Blanks and tabs may be embedded as part of an argument if escaped or quoted.
Characters enclosed in quotes (single or double) are taken literally,
and the delimiting quotes are removed.
Outside of quoted strings a backslash
\f1(\f4\e\f1)
escapes the next character.
.PP
Each argument list is constructed starting with the
.IR initial-arguments ,
followed by some number of
arguments read from standard input
(Exception: see
\f4\-i\f1
flag).
Flags
\f4\-i\f1,
\f4\-l\f1,
and
\f4\-n\f1
determine how arguments are selected for each command invocation.
When none of these flags are coded,
the
.I initial-arguments\^
are followed by arguments read continuously from standard input until an internal buffer is full,
and then
.I command\^
is executed with the accumulated args.
This process is repeated
until there are no more args.
When there are flag conflicts (e.g.,
\f4\-l\f1
vs.
\f4\-n\f1),
the last flag has precedence.
Valid
.I flags
are:
.TP 15
\f4\-l\f2number\^\f1
.I command\^
is executed for each non-empty
.I number\^
lines of arguments from standard input.
The last invocation of
.I command\^
will be with fewer lines of arguments if fewer than
.I number\^
remain.
A line is considered to end with the first new-line
.I unless\^
the last character of the line is a blank or a tab;
a trailing blank/tab signals continuation through the next non-empty line.
If
.I number\^
is omitted, 1 is assumed.
Option
\f4\-x\f1
is forced.
.TP
\f4\-i\f2replstr\^\f1
Insert mode:
.I command\^
is executed for each line from standard input,
taking the entire line as a single arg, inserting it in
.I initial-arguments\^
for each occurrence of
.IR replstr .
A maximum of 5 arguments in
.I initial-arguments\^
may each contain one or more instances of
.IR replstr .
Blanks and tabs at the beginning of each line are thrown away.
Constructed arguments may not grow larger than 255 characters, and option
\f4\-x\f1
is also forced.
\f4{\|}\f1
is assumed for
.I replstr\^
if not specified.
.TP
\f4\-n\f2number\^\f1
Execute
.I command\^
using as many standard input arguments as possible, up to
.I number\^
arguments maximum.
Fewer arguments are used if their total size is greater than
.I size\^
characters, and for the last invocation if there are fewer than
.I number\^
arguments remaining.
If option
\f4\-x\f1
is also coded, each
.I number\^
arguments must fit in the
.I size\^
limitation, else
\f4xargs\fP
terminates execution.
.TP
\f4\-t\f1
Trace mode: The
.I command\^
and each constructed argument list are echoed to file descriptor 2
just prior to their execution.
.TP
\f4\-p\f1
Prompt mode: The user is asked whether to execute
.I command\^
each invocation. Trace mode (\c
\f4\-t\c\f1
) is turned on to print the command instance to be executed,
followed by a \f4?.\|.\|.\fP prompt.
A reply of
\f4y\f1
(optionally followed by anything) executes the command; anything else, including
just a carriage return, skips that particular invocation of
.IR command .
.TP
\f4\-x\f1
Causes
\f4xargs\fP
to terminate if any argument list would be greater than
.I size\^
characters;
\f4\-x\f1
is forced by the options
\f4\-i\f1
and
\f4\-l\f1.
When neither of the options
\f4\-i\f1,
\f4\-l\f1,
or
\f4\-n\f1
are coded, the total length of all arguments must be within the
.I size\^
limit.
.TP
\f4\-s\f2size\^\f1
The maximum total size of each argument list is set to
.I size\^
characters;
.I size\^
must be a positive integer less than or equal to 470. If
\f4\-s\f1
is not coded, 470 is taken as the default.
Note that the character count for
.I size\^
includes one extra character for each argument and the count of characters in the command name.
.TP
\f4\-e\f2eofstr\^\f1
.I eofstr\^
is taken as the logical end-of-file string.
Underbar (\|_\|) is assumed for
the logical \f4\s-1EOF\s+1\fP string
if \f4\-e\fP is not coded.
The value
\f4\-e\fP with no
.I eofstr\^
coded turns off the logical \f4\s-1EOF\s+1\fP string capability
(underbar is taken literally).
\f4xargs\fP
reads standard input until either end-of-file or the logical \f4\s-1EOF\s+1\fP string is encountered.
.PP
\f4xargs\fP
terminates if either it receives a return code of
\f4\-1\f1
from,
or if it cannot execute,
.IR command .
When
.I command\^
is a shell program,
it should explicitly
\f4exit\fP
(see
\f4sh\fP(1))
with an appropriate value to avoid accidentally returning with
\f4\-1\f1.
.SH EXAMPLES
The following examples moves all files from directory $1 to directory $2, and echo each move
command just before doing it:
.PP
.RS
.ft 4
ls \|$1 \|| \|xargs \|\-i \|\-t \|mv \|$1/{\|} \|$2/{\|}
.ft 1
.RE
.PP
The following example combines the output of the parenthesized commands onto one line,
which is then echoed to the end of file \f4log\fP:
.PP
.RS
.ft 4
(logname; \|date; \|echo \|$0 \|$\(**) \|| \|xargs \|>>log
.ft 1
.RE
.PP
The user is asked which files in the current directory are to be archived
and archives them into
\f4arch\f1
(1.) one at a time, or (2.) many at a time.
.PP
.RS
1.\f4\ \|\ \|ls \|| \|xargs \|\-p \|\-l \|ar \|r \|arch\fP
.br
2.\f4\ \|\ \|ls \|| \|xargs \|\-p \|\-l \|| \|xargs \|ar \|r \|arch\fP
.RE
.PP
The following example executes
\f4diff\fP"(1)"
with successive
pairs of arguments originally typed as shell arguments:
.PP
.RS
.ft 4
echo \|$\(** \|| \|xargs \|\-n2 \|diff
.ft 1
.RE
.SH "SEE ALSO"
\f4sh\fP(1).
.\"	@(#)xargs.1	6.2 of 9/2/83
.Ee
