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

.. highlight:: none


Synopsis
========

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

:command:`para` :option:`-k 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:`-k` 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 :option:`-c` has not been given and a job exits with a non-zero status
not ignored with :option:`-i`, or if a job exits because it caught
a signal, or if the timeout set with :option:`-t` is reached, running jobs
are sent a `TERM`, pending jobs are discarded, and :command:`para`
exits. If a process group leader does not terminate within 120 seconds,
or the time set with :option:`-g`, after `TERM` was sent, its process
group is killed.

If :option:`-f` is given and a job exits with a non-zero status, or
if :command:`para` is sent `USR1`, pending jobs are discarded and
:command:`para` exits as soon as all running jobs have finished.

Suspending :command:`para` with :kbd:`Ctrl-Z` also suspends running jobs;
resuming :command:`para` with :manpage:`bg(1)` or :manpage:`fg(1)` also 
resumes suspended jobs.


Options
=======

.. option:: -C

    Print Para's build configuration.

.. option:: -c

    Continue when a job returns an error.

.. option:: -e fd

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

.. option:: -f

    Let running jobs finish when a job returns an error.

.. option:: -g n

    Give jobs `n` secs to terminate when aborted (default: 120). Set
    to 0 to give jobs unlimited time.

.. option:: -h

    Show a help screen.

.. option:: -i n

    Do not treat exit status `n` as error.

.. option:: -j n

    Run up to `n` jobs in parallel. Defaults to the number of
    processors (or 2 if that number cannot be detected).

.. option:: -k format

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

.. 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
    (or 2.0 if that number cannot be detected). 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:: -r str

    Use `str` as replacement string for :option:`-k` (default: ``{}``).

.. option:: -q

    Suppress job output, including errors.

.. option:: -t n

    Abort after `n` seconds.

.. option:: -V

    Show version and legal information.

.. option:: -v

    Be more verbose.

:option:`-i` can be given multiple times.


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 ignored with :option:`-i`. 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 caught


Caveats
=======

If :manpage:`getloadavg(3)` is not available, :command:`para` will
silently run as many jobs in parallel as processors are online 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 -k 'echo {}' foo bar baz
    foo
    bar
    baz

Add ``FOO=bar`` and ``BAZ=qux`` to the job environment::

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

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 -k '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 succeeded, 0 failed
    $ cat jobs.out
    foo
    $ cat jobs.err
    bar


See Also
========

:manpage:`xargs(1)`, :manpage:`getloadavg(3)`