sbase/xargs.1

.Dd 2015-10-08
.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 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 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.
Use ISO-date-format in manpages The one specified by mdoc is hard to read for non-native speakers from countries which read the date day-first (like Germany, Greece, North-Korea, Swamp,...). This is also consistent with how we generally specify dates at suckless.org. 2015-10-08 11:15:08 -04:00			`.Dd 2015-10-08`
remove sbase-VERSION from man page, fix sponge.1 date 2015-01-31 08:20:02 -05:00			`.Dt XARGS 1`
Add .Os sbase and sed replace to .Os sbase $(VERSION) in make install 2015-01-31 14:37:03 -05:00			`.Os sbase`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Sh NAME`
			`.Nm xargs`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Nd construct argument lists and execute command`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Sh SYNOPSIS`
			`.Nm`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Op Fl rtx`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Op Fl E Ar eofstr`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Op Fl n Ar num`
			`.Op Fl s Ar num`
			`.Op Ar cmd Op Ar arg ...`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Sh DESCRIPTION`
man pages: improve consistency 2015-02-01 14:52:28 -05:00			`.Nm`
			`reads space, tab, newline and EOF delimited strings from stdin`
			`and executes the specified`
			`.Ar cmd`
			`with the strings as`
			`.Ar arguments .`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Pp`
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			`Any arguments specified on the command line are given to the command upon`
			`each invocation, followed by some number of the arguments read from`
man pages: improve consistency 2015-02-01 14:52:28 -05:00			`stdin. The command is repeatedly executed one or more times until stdin`
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			`is exhausted.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Pp`
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			Spaces, tabs and newlines may be embedded in arguments using single (`'')
xargs.1: dont justify text, remove " " 2015-02-06 09:43:46 -05:00			or double (`"') quotes or backslashes ('\\'). Single quotes escape all
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			`non-single quote characters, excluding newlines, up to the matching single`
xargs.1: dont justify text, remove " " 2015-02-06 09:43:46 -05:00			`quote. Double quotes escape all non-double quote characters, excluding`
			`newlines, up to the matching double quote. Any single character, including`
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			`newlines, may be escaped by a backslash.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Sh OPTIONS`
			`.Bl -tag -width Ds`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.It Fl n Ar num`
man pages: improve consistency 2015-02-01 14:52:28 -05:00			`Use at most`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Ar num`
man pages: improve consistency 2015-02-01 14:52:28 -05:00			`arguments per command line.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It Fl r`
xargs.1: dont justify text, remove " " 2015-02-06 09:43:46 -05:00			`Do not run the command if there are no arguments. Normally the command is`
Add initial version of xargs(1) 2014-01-03 06:52:47 -05:00			`executed at least once even if there are no arguments.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It Fl E Ar eofstr`
man pages: improve consistency 2015-02-01 14:52:28 -05:00			`Use`
			`.Ar eofstr`
			`as a logical EOF marker.`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.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.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.El`
			`.Sh EXIT STATUS`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Nm`
			`exits with one of the following values:`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.Bl -tag -width Ds`
			`.It 0`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`All invocations of`
			`.Ar cmd`
			`returned a zero exit status.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 123`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`One or more invocations of`
			`.Ar cmd`
			`returned a nonzero exit status.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 124`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Ar cmd`
			`exited with a 255 exit status.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 125`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Ar cmd`
			`was killed or stopped by a signal.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 126`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Ar cmd`
			`was found but could not be executed.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 127`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Ar cmd`
			`could not be found.`
mandoc: convert uname.1, uniq.1 and xargs.1 2015-01-30 15:51:23 -05:00			`.It 1`
			`Some other error occurred.`
			`.El`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Sh STANDARDS`
			`The`
			`.Nm`
			`utility is compliant with the`
POSIX 2013 audit Mostly manpage-shuffling according to the changes in the corrigendum, wording changes and more idiomatic expressions. All this is finished up by marking the POSIX 2013 conformant tools with .St -p1003.1-2013 which is not available in older mandoc builds or nroff, but which reflects what we actually did, so who cares? This is a huge step and it's not far until we can release sbase 0.1. 2015-03-27 12:22:48 -04:00			`.St -p1003.1-2013`
			`specification except from the`
Add s-, t-, x-flags to and audit xargs(1) The flexible design already allowed to add these flags trivially. Drop the -I and -L-flags, which are XSI-extensions. The audit generally consisted of style-changes, dropping kitchen- sink functions, updating the usage and using estrtonum instead of strtol. 2015-03-22 17:53:12 -04:00			`.Op Fl p`
			`flag.`
			`.Pp`
			`The`
			`.Op Fl r`
			`flag is an extension to that specification.`