
call_c(+Function, ?Code)

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



Arguments
   Function            Atom or structure
   Code                Variable, integer or structure

Type
   External Interface

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 --- Function is not instantiated.
     5 --- Function is neither an atom nor a structure.
     5 --- An argument of Function has a type which cannot be    translated.
    20 --- Arithmetic exception in the function or when converting a    single-precision float to a double.
    31 --- Arity of Function exceeds 10.
    41 --- The array argument of Function does not exist.
   211 --- 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
