.. _library_process:

``process``
===========

This library provides a portable abstraction over process handling
predicates found in some backend Prolog systems. Currently supports
ECLiPSe, GNU Prolog, SICStus Prolog, SWI-Prolog, Trealla Prolog, and
XVM.

API documentation
-----------------

Open the
`../../docs/library_index.html#process <../../docs/library_index.html#process>`__
link in a web browser.

Loading
-------

To load all entities in this library, load the ``loader.lgt`` file:

::

   | ?- logtalk_load(process(loader)).

Testing
-------

To test this library predicates, load the ``tester.lgt`` file:

::

   | ?- logtalk_load(process(tester)).

Usage
-----

The ``process`` object provides the following predicates for portable
process handling:

- ``create(Executable, Arguments, Options)`` - Creates a new process
- ``wait(Process, Status)`` - Waits for a process to terminate
- ``kill(Process, Signal)`` - Terminates a process with a specific
  signal
- ``kill(Process)`` - Terminates a process using the default signal
  (SIGKILL)

Exit status depends on the backend. For a successfully terminated
process, ``Status`` is either ``0`` or ``exit(0)``. For unsuccessful
processes, ``Status`` cannot be sensibly abstracted. Consult the backens
documentation for the details.

The ``create/3`` predicate supports the following options:

- ``process(Pid)`` - Unifies Pid with the process identifier (an opaque
  ground term)
- ``stdin(Stream)`` - Binds Stream to the process standard input
- ``stdout(Stream)`` - Binds Stream to the process standard output
- ``stderr(Stream)`` - Binds Stream to the process standard error
- ``type(Type)`` - Sets the type (``binary`` or ``text``) of the
  ``stdin/1`` and ``stdout/1`` streams

Process identifiers (PIDs) should be treated as opaque ground terms.
Their internal representation varies between backend Prolog systems.

The ``type/1`` option is ignored on ECLiPSe, GNU Prolog, Trealla Prolog,
and XVM as these systems don't provide the necessary support to set the
streams type at process creation.

Example:

::

   | ?- process::create('/bin/echo', ['hello.'], [stdout(Out), process(PID)]),
        read_term(Out, Term, []),
        close(Out).
   Out = ..., PID = ..., Term = hello.
