[ Operating System | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# exec(++Command, ++Streams)

A child process Command is forked, its standard streams are connected to Streams and the ECLiPSe process waits until it terminates.

Command
  String, atom or list of atomic terms.
Streams
  List of stream ids.

## Description

This predicate is used to fork a child process and to set up pipes to its standard streams. After the process is forked, ECLiPSe blocks, i.e. it waits until the child process terminates.

Command should be a list with at least one element: The first list element (a path name in ECLiPSe path name syntax, atom or string) specifies the program to be executed, and the subsequent list elements are its arguments. The arguments can be atoms, strings or numbers. They are passed to the executed program literally (in particular, no path name syntax conversion is applied).

For backward compatibility, Command can be a simple atom or string, in which case the first word in Command specifies the program to be executed, and the following words are its command-line arguments. This form is deprecated since it creates problems with argument quoting and operating system dependent path name syntax.

By specifying the Streams argument it is possible to control which of the process' standard streams are connected to ECLiPSe streams. The form of Streams is [Stdin, Stdout, Stderr]. If some of these streams are specified and not null, a pipe is opened which connects the standard stream of the child process with the specified ECLiPSe stream, e.g. Stdin must be an output stream because it is connected to the standard input of the child process. If the list Streams is shorter, only the specified streams are connected with a pipe. The streams can be specified like for open/3. If the stream is a variable, it is bound to the physical stream number, if it is an atom different from null, that symbolic stream is used. Specifying a null stream means that no pipe is set up for this stream.

Each stream can also be specified as sigio(Stream) (UNIX systems only). In this case a pipe is set up to the stream Stream and in addition the pipe is instructed to send the signal io each time new data appears in it. In this way the two processes can communicate in a truly asynchronous way. When one process sends data to the other one, the interrupt handler is invoked and it can read and process the data. When it finishes, it can continue where it was interrupted.

exec(Command, Streams) is equivalent to

exec(Command, Streams, Pid), wait(Pid, _)

exec(Command, []) is very similar to system(Command).

### Modes and Determinism

- exec(++, ++) is det

### Exceptions

(4) instantiation fault
  Command is not instantiated.
(5) type error
  Command is instantiated, but not to a string or an atom.
(5) type error
  Streams is instantiated, but not to a list.
(5) type error
  A stream in Streams is instantiated, but not to an atom.
(170) system interface error
  System error, it was not possible to fork the child or the exec system call in the child failed.
(192) illegal stream mode
  The specified stream is not open in the appropriate mode.

## Examples

    Success:
          % exec/2 wait for the child process
          [eclipse]: exec(ls, []), write(end_exec).
          aux.o           coroutine.pl    kegi.pl         sepia.o
          bsi.pl          cprolog.pl      lint.pl         sorts.pl
          cio.pl          history.pl      lists.pl        strings.pl
          cn.pl           k_env.pl        quintus.pl      t_all.pl
          end_exec
          yes.

          % exec/3 return immediately
          [eclipse]: exec(ls, [], Pid), write(end_exec).
          end_exec
          Pid = 16054
          yes.
          [eclipse]: aux.o  coroutine.pl    kegi.pl         sepia.o
          bsi.pl          cprolog.pl      lint.pl         sorts.pl
          cio.pl          history.pl      lists.pl        strings.pl
          cn.pl           k_env.pl        quintus.pl      t_all.pl

    Error:
          exec(S, [output]).         (Error 4).
          exec(ls, null).            (Error 5).
          exec(chipc, [f(output)]).  (Error 5).
          exec(date, [input]).       (Error 192).

## See Also

call_c / 2, exec / 3, exec_group / 3, setenv / 2, wait / 2, kill / 2, sh / 1, system / 1, open / 3