******
Manual
******

.. highlight:: none


Synopsis
========

:command:`para` [:option:`variable`...] :option:`command` [...]

:command:`para` :option:`-c format` [:option:`variable`...] :option:`argument` [...]

:command:`para` :option:`-C` | :option:`-V` | :option:`-h`


Description
===========

:command:`para` runs :option:`commands <command>` in parallel,
adding :option:`variables` to their environment.

:option:`Commands <command>` are split into words in the same way as they
are split by the :command:`sh`, save for that escaped newlines are
interpreted as newlines and that trailing escapes raise a syntax error.

If :option:`-c` is given, commands are composed by replacing each ``{}``,
or each occurrence of the placeholder set with :option:`-r`, in the
`format` with the next :option:`argument`. Placeholders must occur as
words of their own; placeholders that occur within words are treated as
ordinary characters. The `format` is split into words in the same way as
:option:`commands <command>` are. Word-splitting precedes placeholder
substitution.

Started processes are made process group leaders.

If an error occurs, running jobs are terminated and pending jobs are
discarded. If :option:`-k` is given and a process group leader does not
terminate within the given grace period, its process group is killed.

:kbd:`Ctrl-Z` also stops runnings jobs. Continuing with :manpage:`bg(1)` or
:manpage:`fg(1)` continues them again. Sending :c:macro:`SIGUSR1` discards
pending jobs but will leave running jobs alone.

:command:`para` exits when all jobs have exited.


Options
=======

.. option:: -C

    Show the build configuration.

.. option:: -c format

    Compose commands by replacing ``{}``'s in `format`
    with :option:`arguments <argument>`.

.. option:: -e fd

    Write non-job output, including errors, to file descriptor `fd`.

.. option:: -h

    Show a help screen.

.. option:: -i

    Neither terminate runnings jobs nor discard pending ones
    when a job returns an error.

.. option:: -j n

    Run `n` jobs in parallel. Defaults to the number of
    processors available or 2, whichever is higher.

.. option:: -k n

    Kill jobs that do not exit within `n` seconds after
    they have been requested to terminate.

.. option:: -l n

    Only start jobs if no jobs are running or the one minute load
    average is smaller than `n`. Defaults to one less than the number
    of processors available or 2.0, whichever is higher. Set to 0 to run
    as many jobs in parallel as requested with :option:`-j`. Only
    available on systems that support :manpage:`getloadavg(3)`.

.. option:: -n status

    Do not treat a job exiting with `status` as error. Give
    multiple times to exempt multiple statuses.

.. option:: -r str

    Use `str` as placeholder in :option:`format <-c>` (default: ``{}``).

.. option:: -q

    Suppress job output, including errors.

.. option:: -t n

    Time out after n seconds.

.. option:: -V

    Show version and legal information.

.. option:: -v

    Be more verbose.

.. option:: -w

    Wait for running jobs to finish when a job returns an error. Pending
    jobs are still discarded.


Diagnostics
===========

Arguments are invalid if they cannot be split into words; this happens
when they contain unbalanced quotes or end with an escape (:samp:`\\`).


Exit Status
===========

:command:`para` exits with the same status as the last job that has exited
with a non-zero status not exempted with :option:`-n`. If no job has been
been started yet, all jobs have exited with such a status, a signal was
caught, or an unexpected error occurred, :command:`para` exits with:

0
    Success

1
    Failure

2
    Usage error

> 128
    Signal


Caveats
=======

How long applications take to terminate varies. Use :option:`-k` with caution.

If :manpage:`getloadavg(3)` is not available, :command:`para` will
silently run as many jobs in parallel as processors are available or
as requested with :option:`-j`.


Bugs
====

Please report bugs at <https://github.com/odkr/para/issues>.


Examples
========

Run :command:`echo foo` and :command:`echo bar` in parallel::

    $ para 'echo foo' 'echo bar'
    bar
    foo

Compose commands from arguments::

    $ para -c 'echo {}' foo bar baz
    foo
    bar
    baz

Add ``FOO=bar`` to the job environment::

    $ para FOO=bar 'sh -c "echo $FOO"'
    bar

Rename files from :file:`{x}.foo` to :file:`{x}.bar`:

.. code:: bash

    $ for file in *.foo
    > do printf '%s\0' "$file" "${file%.foo}.bar"
    > done |
    > # Without -n, xargs would read all input before calling para
    > xargs -0 -n256 para -c 'mv {} {}'

Of course, if your :manpage:`xargs(1)` supports :option:`-L` and
:option:`-P`, just do:

.. code:: bash

    $ for file in *.foo
    > do printf '%s\0' "$file" "${file%.foo}.bar"
    > done |
    > xargs -0 -L2 -P4 mv

Show which jobs have been started and redirect job output::

    $ exec 3>&2
    $ para -ve3 'echo foo' 'sh -c "echo bar >&2"' >jobs.out 2>jobs.err
    para: [31744] echo foo
    para: [31747] sh -c echo\ bar\ >&2
    para: Waiting for 1 job to finish...
    para: 2 jobs run, 0 failed
    $ cat jobs.out
    foo
    $ cat jobs.err
    bar


See Also
========

:manpage:`xargs(1)`