sbase/xargs.1

105 lines
2.3 KiB
Groff

.Dd 2023-07-30
.Dt XARGS 1
.Os sbase
.Sh NAME
.Nm xargs
.Nd construct argument lists and execute command
.Sh SYNOPSIS
.Nm
.Op Fl rtx
.Op Fl E Ar eofstr
.Op Fl I Ar replstr
.Op Fl n Ar num
.Op Fl s Ar num
.Op Ar cmd Op Ar arg ...
.Sh DESCRIPTION
.Nm
reads space, tab, newline and EOF delimited strings from stdin
and executes the specified
.Ar cmd
with the strings as
.Ar arguments .
.Pp
Any arguments specified on the command line are given to the command upon
each invocation, followed by some number of the arguments read from
stdin.
The command is repeatedly executed one or more times until stdin is exhausted.
.Pp
Spaces, tabs and newlines may be embedded in arguments using single (`'')
or double (`"') quotes or backslashes ('\\').
Single quotes escape all non-single quote characters, excluding newlines, up
to the matching single quote.
Double quotes escape all non-double quote characters, excluding newlines, up
to the matching double quote.
Any single character, including newlines, may be escaped by a backslash.
.Sh OPTIONS
.Bl -tag -width Ds
.It Fl n Ar num
Use at most
.Ar num
arguments per command line.
.It Fl r
Do not run the command if there are no arguments.
Normally the command is executed at least once even if there are no arguments.
.It Fl E Ar eofstr
Use
.Ar eofstr
as a logical EOF marker.
.It Fl I Ar replstr
Use
.Ar replstr
as the placeholder for the argument.
Sets the arguments count to 1 per command line.
It also implies the option x.
.It Fl s Ar num
Use at most
.Ar num
bytes per command line.
.It Fl t
Write the command line to stderr before executing it.
.It Fl x
Terminate if the command line exceeds the system limit or the number of bytes
given with the
.Op Fl s
flag.
.El
.Sh EXIT STATUS
.Nm
exits with one of the following values:
.Bl -tag -width Ds
.It 0
All invocations of
.Ar cmd
returned a zero exit status.
.It 123
One or more invocations of
.Ar cmd
returned a nonzero exit status.
.It 124
.Ar cmd
exited with a 255 exit status.
.It 125
.Ar cmd
was killed or stopped by a signal.
.It 126
.Ar cmd
was found but could not be executed.
.It 127
.Ar cmd
could not be found.
.It 1
Some other error occurred.
.El
.Sh STANDARDS
The
.Nm
utility is compliant with the
.St -p1003.1-2013
specification except from the
.Op Fl p
flag.
.Pp
The
.Op Fl r
flag is an extension to that specification.