Skip to Content
gnux

xargsx

Build and run command lines from standard input.

Mirrors GNU xargs. Run it as xargsx, or as gnux xargsx.

Synopsis

xargsx [OPTION]... [COMMAND [INITIAL-ARGUMENT]...]

GNU reference

Description

xargsx reads items from standard input and runs COMMAND (echo when none is given) with the INITIAL-ARGUMENTs followed by the items, as many per command line as fit, until the input is used up. Items are separated by blanks and newlines; single quotes, double quotes and a backslash protect a character from being a separator, a quote must close on the line it opens on, and a blank line is ignored. Because file names may hold blanks, quotes and newlines, pair -0 with a producer that separates names with NUL (findx -print0), or use -d to name a single delimiter character (C escapes such as \n and \t, octal \NNN and hexadecimal \xHH are understood); with either, every other character is literal. -a reads the items from a file and leaves standard input to the commands; otherwise each command gets an empty standard input, so that it cannot consume the items. -E names a logical end-of-input item (not with -0 or -d). -n limits the items per command and -L the non-blank input lines per command (a line that ends in a blank continues on the next one). -s sets the size limit of a command line, counting the command, the initial arguments, the items and one terminating NUL for each: the default is 131072 bytes, or the system's limit when that is smaller, taken as 524288 bytes on Unix and 32767 on Windows, less 2048 and less the size of the environment. -x fails with 'argument list too long' when the items asked for with -n or -L do not fit, instead of running a shorter command. -I runs the command once per input line and replaces every REPLACE-STR in the command and its initial arguments with the line (leading blanks removed, quotes still processed); it implies -x and -L 1, and -L implies -x. Without -r the command runs once even when the input holds no items. -t prints each command line on the error stream before running it, quoted so that it can be pasted into a shell; -p prints it followed by '?...' and runs it only when the line read from the terminal (/dev/tty, or the console on Windows) begins with y or Y. -P runs up to MAX-PROCS commands at once; their output is not grouped, so lines of different commands may interleave. A command that exits with status 255, or that a signal ends, stops xargsx at once; any other nonzero status lets the remaining commands run and makes the final status 123.

Differences from GNU xargs: a COMMAND named after a gnux tool, by its own name (rmx) or its GNU name (rm, echo), runs inside the xargsx process instead of as a program found on PATH, so that 'xargsx rm' works where no GNU tools are installed; any other name is a program found on PATH. Use 'envx COMMAND' as the command to force the program on PATH. GNU's last-one-wins between conflicting options is replaced by a fixed precedence toward the most cautious one, in any order: -I/-i wins over -L/-l, which wins over -n, each with GNU's warning about the ignored option; -0 wins over -d; and of two spellings of one option, -I wins over -i, -L over -l and -E over -e. -P 0 runs at most 128 commands at once rather than as many as the system allows. The system's command-line limit is the fixed figure above, not one asked of the system. A NUL in the input outside -0 mode is dropped with GNU's warning, where GNU cuts the item short at it. A quote left open at the very end of the input is always an error. -o/--open-``tty and --process-slot-var are not supported and are refused with a usage error. Changing -P while xargsx runs, with SIGUSR1 and SIGUSR2, is not available.

Permissions

xargsx needs read permission on the -a file. Running a program needs execute permission on it and search permission on the directories leading to it; a gnux tool run in-process needs whatever that tool needs for the files it is given (rm needs write permission on the containing directory, and so on). The commands run with the privileges of xargsx itself.

Use cases

  • Removing, moving or checksumming the files a search produced, a few commands for thousands of names.
  • Handling file names with spaces, quotes or newlines safely with -0 and a NUL-separated producer.
  • Running one command per input line with the line placed anywhere in it using -I.
  • Splitting a long list into commands of N arguments with -n.
  • Running independent jobs in parallel with -P.
  • Reviewing destructive commands before they run with -t, or approving each one with -p.
  • Keeping a command line under a size limit with -s when a program rejects long ones.
  • Skipping the command entirely when a search found nothing, with -r.
  • Feeding items from a file with -a while the command keeps the terminal as its standard input.
  • Writing scripts that remove or copy files the same way on machines with no GNU tools installed.

Flags

  -a, --arg-file FILE               read arguments from FILE, not standard input
  -d, --delimiter CHARACTER         items in the input are separated by CHARACTER, not by whitespace;
                                    disables quote and backslash processing and logical EOF processing
  -e, --eof END[="                  "]�equivalent to -E END if END is specified; otherwise, there is no end-of-file string
  -E, --eof-string END              set logical EOF string to END; if END occurs as an item of input,
                                    the rest of the input is ignored (ignored if -0 or -d was specified)
  -x, --exit                        exit if the size (see -s) is exceeded
      --help                        display this help and exit
  -p, --interactive                 prompt before running commands
  -n, --max-args MAX-ARGS           use at most MAX-ARGS arguments per command line
  -s, --max-chars MAX-CHARS         limit length of command line to MAX-CHARS
  -L, --max-input-lines MAX-LINES   use at most MAX-LINES non-blank input lines per command line
  -l, --max-lines MAX-LINES[="1"]   similar to -L but defaults to at most one non-blank input line
                                    if MAX-LINES is not specified
  -P, --max-procs MAX-PROCS         run at most MAX-PROCS processes at a time
  -r, --no-run-if-empty             if there are no arguments, then do not run COMMAND;
                                    if this option is not given, COMMAND will be run at least once
  -0, --null                        items are separated by a NUL, not whitespace;
                                    disables quote and backslash processing and logical EOF processing
  -o, --open-tty                    reopen stdin as /dev/tty in the child process before executing
                                    the command (not supported)
      --process-slot-var VAR        set environment variable VAR in child processes (not supported)
  -i, --replace R[="{}"]            replace R in INITIAL-ARGS with names read from standard input,
                                    split at newlines; if R is unspecified, assume {}
  -I, --replace-string R            same as --replace=R
      --show-limits                 show limits on command-line length
  -t, --verbose                     print commands before executing them
      --version                     output version information and exit

Examples

Join the items of several lines into one command line

printfx 'a b\nc\n' | xargsx echox

Remove the files a search found, whatever characters their names hold

findx . -name '*.tmp' -print0 | xargsx -0 rmx -f

Do nothing at all when the search finds no file

findx . -name '*.orig' -print0 | xargsx -0 -r rmx

Pass two items to each command

seqx 6 | xargsx -n 2 echox

Run one command per line, with the line placed inside an argument

printfx 'a.txt\nb.txt\n' | xargsx -I {} cpx {} {}.bak

Treat each line as one item, blanks and quotes included

xargsx -d '\n' -a names.txt touchx
seqx 4 | xargsx -t -n 2 echox

Ask before each removal (the answer is read from the terminal)

lsx | xargsx -p -n 1 rmx

Checksum many files four commands at a time

findx . -type f -print0 | xargsx -0 -n 50 -P 4 sha256sumx

Use one input line per command, as -L counts them

printfx 'a b\nc d\n' | xargsx -L 1 echox line:

Stop reading at a marker item

printfx 'a b END c\n' | xargsx -E END echox

Keep every command line within 20 bytes

seqx 10 | xargsx -s 20 echox

Run a program from PATH rather than the gnux tool of the same name

printfx 'a b\n' | xargsx envx echo

Tell a failing command (status 123) from a missing one (127)

echox x | xargsx no-such-command; echox "status: $?"

Show the size limits in effect without running anything

xargsx --show-limits -r < /dev/null

Options

Each option has a page of its own, with its usage and examples.

  • -a, --arg-file: Read arguments from FILE, not standard input.
  • -d, --delimiter: Items in the input are separated by CHARACTER, not by whitespace; disables quote and backslash processing and logical EOF processing.
  • -e, --eof: Equivalent to -E END if END is specified; otherwise, there is no end-of-file string.
  • -E, --eof-string: Set logical EOF string to END; if END occurs as an item of input, the rest of the input is ignored (ignored if -0 or -d was specified).
  • -x, --exit: Exit if the size (see -s) is exceeded.
  • -p, --interactive: Prompt before running commands.
  • -n, --max-args: Use at most MAX-ARGS arguments per command line.
  • -s, --max-chars: Limit length of command line to MAX-CHARS.
  • -L, --max-input-lines: Use at most MAX-LINES non-blank input lines per command line.
  • -l, --max-lines: Similar to -L but defaults to at most one non-blank input line if MAX-LINES is not specified.
  • -P, --max-procs: Run at most MAX-PROCS processes at a time.
  • -r, --no-run-if-empty: If there are no arguments, then do not run COMMAND; if this option is not given, COMMAND will be run at least once.
  • -0, --null: Items are separated by a NUL, not whitespace; disables quote and backslash processing and logical EOF processing.
  • -o, --open-tty: Reopen stdin as /dev/tty in the child process before executing the command (not supported).
  • --process-slot-var: Set environment variable VAR in child processes (not supported).
  • -i, --replace: Replace R in INITIAL-ARGS with names read from standard input, split at newlines; if R is unspecified, assume {}.
  • -I, --replace-string: Same as --replace=R.
  • --show-limits: Show limits on command-line length.
  • -t, --verbose: Print commands before executing them.

Exit status

StatusMeaning
0every command ran and exited with status 0
1xargsx itself failed: a bad option value, an unmatched quote, an argument line too long, an input file it could not open
123a command exited with a status from 1 to 254 (the remaining commands still ran)
124a command exited with status 255; no further command was started
125a signal ended a command; no further command was started
126the command was found but could not be run
127the command was not found

Help in the terminal

xargsx --help                # options, first examples, exit status
gnux help xargsx             # this page: the full manual
gnux help xargsx --OPTION    # one option in depth, with its examples

See also

On this page