[ External Interface | The ECLiPSe Built-In Predicates | Reference Manual | Alphabetic Index ]

# call_c(+Function, ?Code)

Invoke the C function Function and unify its return code with Code.

Function
  Atom or structure
Code
  Variable, integer or structure

## Description

This predicate allows to call C functions directly from Prolog. The arguments of Function are translated as follows:

* integers and floats are passed directly

* strings and atoms are passed as C strings

* terms Name/Arity are interpreted as arrays and a pointer to the first array's element is passed

* structures in the form ar(M, N, K) are interpreted as array elements and a pointer to this array element is passed.

C numbers and strings are thus mapped directly on Prolog constants, C structures are mapped on Prolog arrays. If Code is a variable or an integer, it will be unified with the (integer) return code of the function. If the function return value is of another type, it must be specified in the Code as follows:

* integer(Code) denotes an integer

* float(Code) denotes a (double precision) floating point number

* string(Code) denotes a string

After Function finishes, Code is unified with its return code. If Function is a system function and the return code is -1, the flag last_errno contains the errno value set by the command. Function can have at most 10 arguments (floating-point arguments count as two). Note that only functions linked with the current session can be called. Other functions can be dynamically linked using the load/1 predicate. The first time a function is called it takes longer because the system has to find the function in the symbol table of the binary. Its address is remembered and thus next calls are faster.

### Modes and Determinism

- call_c(+, ?) is det

### Exceptions

(4) instantiation fault
  Function is not instantiated.
(5) type error
  Function is neither an atom nor a structure.
(5) type error
  An argument of Function has a type which cannot be translated.
(20) arithmetic exception
  Arithmetic exception in the function or when converting a single-precision float to a double.
(31) arity limit exceeded
  Arity of Function exceeds 10.
(41) array or global variable does not exist
  The array argument of Function does not exist.
(211) External function does not exist
  The specified C function does not exist.

## Examples

    Success:
        [eclipse 16]: make_array(time(4), integer).

        yes.
        [eclipse 17]: call_c(gettimeofday(time/1, time(2)), X).

        X = 0
        yes.
        [eclipse 18]: getval(time(0), Sec1Jan70), getval(time(2), MinWest),
                  getval(time(3), DstTime).

        Sec1Jan70 = 733148538
        MinWest = -60
        DstTime = 4
        yes.
        [eclipse 19]: call_c(ctime(time(0)), string(Date)).

        Date = "Fri Mar 26 13:22:18 1993\n"
        yes.
        [eclipse 20]: call_c(sinh(1.5), float(X)).
        External function does not exist in call_c(sinh(1.5), float(X))
        [eclipse 21]: load("-u _sinh -lm"), call_c(sinh(1.5), float(X)).

        X = 2.12927938
        yes.

    Error:
          call_c(nofunc, X).                  (Error 211).
          call_c(getrusage(noarray/1, 0)      (Error 41).

## See Also

exec / 2, system / 1