path: root/xe.1

.Dd July 14, 2017
.Dt XE 1
.Os
.Sh NAME
.Nm xe
.Nd execute a command for every argument
.Sh SYNOPSIS
.Nm
.Op Fl 0FLRnv
.Oo Fl p | Fl I Ar replace-arg Oc
.Op Fl N Ar maxargs
.Op Fl j Ar maxjobs
.Ar command\ ...
.Nm
.Op Ar flags\ ...
.Fl f Ar argfile Ar command\ ...
.Nm
.Op Ar flags\ ...
.Fl s Ar shellscript
.Nm
.Op Ar flags\ ...
.Fl a Ar command\ ... Cm -- Ar args\ ...
.Nm
.Op Ar flags\ ...
.Fl A Ar argsep Ar command\ ... Ar argsep Ar args\ ...
.Sh DESCRIPTION
The
.Nm
utility constructs command lines from specified arguments,
combining some of the best features of
.Xr xargs 1
and
.Xr apply 1 .
.Pp
.Nm
means
.Dq execute for every ... .
.Pp
.Nm
supports different methods to specify arguments to commands:
.Bl -tag -width Ds
.It Ar command\ ...
By default, arguments - separated by newlines -
are read from the standard input.
The resulting command is constructed from the command line parameters,
replacing
.Ar replace-arg
(unless
.Fl p
is used, see below)
with the read argument, and is executed with
.Xr execvp 3 .
.Pp
In this mode, no shell is involved and
.Ar replace-arg
must appear as a word on its own, i.e.
.Sq foo {} bar
will work, but
.Sq foo{} bar
will not, where {} is the default value for
.Ar replace-arg .
.Pp
If no argument is specified, the default is
.Sq Ic printf %s\en .
.It Fl f Ar argfile
Read arguments from
.Ar argfile ,
instead of the standard input.
.Pp
This does not close the standard input for execution,
it is passed to the forked process.
.It Fl s Ar shellscript
In this mode, the single parameter
.Ar shellscript
is executed using
.Ic sh -c .
In the script, the specified arguments can be accessed using $1, $2, ...
.Pp
For example:
.Dl echo \(aqa\enb\(aq | xe -N2 \-s \(aqecho $2 $1\(aq
.It Fl a Ar command\ ... Cm -- Ar args\ ...
In this mode, everything after
.Cm --
is passed as
.Ar args
to
.Ar command .
.It Fl A Ar argsep Ar command\ ... Ar argsep Ar args\ ...
Same as
.Fl a ,
but the custom argument separator
.Ar argsep
is used to distinguish between
.Ar command
and its
.Ar args .
.El
.Pp
The options are as follows:
.Bl -tag -width Ds
.It Fl 0
Input filenames are separated by NUL bytes (instead of newlines, which
is the default)
.It Fl F
Fatal:
stop and exit when a command execution fails.
.It Fl L
Run the resulting commands with line-buffered output;
lines from two jobs will not interleave.
When used twice,
or with
.Fl vv ,
also prefix each line with the number of the job
(see
.Sx ENVIRONMENT )
in such a manner that the output can be piped to
.Sq Li sort -snk1
to group it.
.It Fl R
Return with status 122 when no arguments have been specified
(instead of 0, the default).
.Nm
never executes a command when no arguments are specified.
.It Fl n
Dry run: don't run the resulting commands, just print them.
.It Fl v
Verbose: print commands to standard error before running them.
When used twice, also print job id and exit status for each command.
.It Fl p
Enable
.Em percent rules :
this mode disables the default
.Ar replace-arg
substition and enables
.Xr make 1 Ns \&- Ns
style percent rules.
The first argument of
.Ar command\ ...
is regarded as a pattern:
in the pattern, a single occurrence of
.Li Sq \&%
matches one or more characters,
and replaces the first occurrence of
.Li Sq \&%
with the matched string in the remaining arguments,
which are then used as the command to be executed.
.Pp
Multiple runs of patterns and commands are separated by
.Li Sq \&+ .
Only the first matching percent rule is executed;
when no pattern matches, no command is run.
.It Fl I Ar replace-arg
Replace first occurrence of
.Ar replace-arg
(default:
.Cm {} )
in the resulting command with the argument(s).
Pass an empty
.Ar replace-arg
to disable the replace function.
Contrary to
.Xr xargs 1
this will expand into multiple arguments when needed.
.It Fl N Ar maxargs
Pass up to
.Ar maxargs
arguments to each command (default: 1).
.br
Using
.Fl N0
will pass as many arguments as possible.
.It Fl j Ar maxjobs
Run up to
.Ar maxjobs
processes concurrently.
Using
.Fl j0
will run as many processes as there are CPU cores running.
If
.Ar maxjobs
ends with an
.Sq Ic x ,
it is regarded as a multiplier of the number of running CPU cores
(rounded down, but using at least one core).
.El
.Sh ENVIRONMENT
The environment variable
.Ev ITER
is passed to the child process and incremented on each command execution.
.Sh EXIT STATUS
.Nm
follows the convention of GNU and OpenBSD xargs:
.Bl -tag -compact -width Ds
.It 0
on success
.It 123
if any invocation of the command exited with status 1 to 125.
.It 124
if the command exited with status 255
.It 125
if the command was killed by a signal
.It 126
if the command cannot be run
.It 127
if the command was not found
.It 1
if some other error occurred
.El
.Pp
Additionally, 122 is returned when
.Fl R
was passed and the command was never executed.
.Sh SEE ALSO
.Xr apply 1 ,
.Xr parallel 1 ,
.Xr xapply 1 ,
.Xr xargs 1
.Sh AUTHORS
.An Leah Neukirchen Aq Mt leah@vuxu.org
.Sh LICENSE
.Nm
is in the public domain.
.Pp
To the extent possible under law,
the creator of this work
has waived all copyright and related or
neighboring rights to this work.
.Pp
.Lk http://creativecommons.org/publicdomain/zero/1.0/