Linking to external code

Linking to external code
Using dynamic libraries and C routines with Euphoria

include adv/dll.e

Functions/Procedures
Subtopics

Linking to external code

[type]
callback
( atom x )

Category: Linking to external code

A callback routine type. Returns zero if x is not a valid address returned by call_back.

See also: callback_id, call_back


Linking to external code

[func]
callback_id
( atom cb )

Category: Linking to external code

Returns the routine id of the given callback address.

See also: callback, callback_id


Linking to external code

[func]
call_back
( object id )

Category: Linking to external code

Get a machine address for an Euphoria procedure.

Parameters

  1. id : an object, either the id returned by routine_id, or a pair {'+', id}.

Returns

An atom, the address of the machine code of the routine. It can be used by Windows, or an external C routine in a Windows .dll or Unix-like shared library (.so) as a 32-bit "call-back" address for calling your Euphoria routine.

Comments
By default, your routine will work with the stdcall convention. On Windows, you can specify its id as {'+', id}, in which case it will work with the CDECL calling convention instead. On non-Microsoft platforms, you should only use simple IDs, as there is just one standard calling convention, i.e. DECL.

You can set up as many call-back functions as you like, but they must all be Euphoria functions (or types) with 0 to 9 arguments. If your routine has nothing to return (it should really be a procedure), just return 0 (say), and the calling C routine can ignore the result.

When your routine is called, the argument values will all be 32-bit unsigned (positive) values. You should declare each parameter of your routine as atom, unless you want to impose tighter checking. Your routine must return a 32-bit integer value.

You can also use a call-back address to specify a Euphoria routine as an exception handler in the Linux/FreeBSD signal() function. For example, you might want to catch the SIGTERM signal, and do a graceful shutdown. Some Web hosts send a SIGTERM to a CGI process that has used too much CPU time.

See also: callback, callback_id


Linking to external code

[func]
c_func
( integer rid, sequence args = {} )

Category: Linking to external code

Call a C function, machine code routine, or translated/compiled Euphoria routine by routine id.

Parameters

  1. rid : an integer, a routine id from define_c_func or define_c_proc.
  2. args : a sequence, the list of parameters to pass to the function.

Returns

An object, whose type and meaning was defined by calling define_c_func or define_c_proc.

Comments

If you declare the arguments of a function as C_STRING, etc. then you can pass sequence values to c_func or c_proc and it will automatically poke the values into memory and pass the pointer to the function instead. The opposite also works if the return type of a function is C_STRING, etc.

The C string will be marked for automatic cleanup (see allocate_string), so if your C function expects to keep the string in memory (which is quite uncommon), you will need to revert to C_POINTER and allocate the string yourself.

See also: define_c_func, define_c_proc, c_proc


Linking to external code

[proc]
c_proc
( integer rid, sequence args = {} )

Category: Linking to external code

Call a C function, machine code routine, or translated/compiled Euphoria routine by routine id.

See also: define_c_func, define_c_proc, c_func


Linking to external code

[func]
define_c_func
( object lib, object routine_name, sequence arg_types, atom return_type )

Category: Linking to external code

Define the paramaters of a C function or machine-code routine that returns a value.

Parameters

  1. lib : an object, either an entry point returned by open_dll, or "" to denote a routine in memory.
  2. routine_name : an object, either the name of a function in the shared library or the memory address of the machine-code routine.
  3. arg_types : a sequence, a list of C Type constants for each argument.
  4. return_type : an atom, the type constant or the return value.

Returns

A small integer, the routine id of the function.

Comments

The length of routine_name should not exceed 1,024 characters.

Use the returned value as the first parameter to c_func or c_proc. A returned value of -1 indicates that the function could not be found.

On Windows, you can add a '+' character as a prefix to the function name. This indicates to Euphoria that the function uses the CDECL calling convention. By default, Euphoria assumes that C routines accept STDCALL convention on Windows. See open_dll on how to force this for all functions in a given library.

If you are not interested in using the value returned by the C function, you should instead define it with define_c_proc and call it with c_proc.

By default, define_c_func will crash your application if it cannot find the function. See Errors and debugging for more details.

See also: define_c_proc, c_func, c_proc


Linking to external code

[func]
define_c_proc
( object lib, object routine_name, sequence arg_types )

Category: Linking to external code

Define the paramaters of a C function or machine-code routine does not return a value.

See also: define_c_func, c_func, c_proc


Linking to external code

[func]
define_c_var
( atom lib, sequence variable_name )

Category: Linking to external code

Gets the memory address of a symbol in a shared library.

Parameters

  1. lib : an atom, the address of the shared library from open_dll
  2. variable_name : a sequence, the name of the exported C variable in the library

Returns

An atom, the memory address of variable_name.

Comments

Once you have the address of a C variable, and you know its type, you can use peek and poke to read or write the value of the variable.

By default, define_c_var will crash your application if it cannot find the variable. See Errors and debugging for more details.

See also: peek, peeks, peek2s, peek2u, peek4s, peek4u, peek_string, peek_wstring, poke, poke2, poke4, poke_string, poke_wstring


Linking to external code

[const]
NULL

Category: Linking to external code

A null pointer.


Linking to external code

[func]
open_dll
( sequence file_name, types:boolean use_cdecl = 0 )

Category: Linking to external code

Open a Windows dynamic link library (.dll) file, or a Unix shared library (.so) file.

Parameters

  1. file_name : a sequence, the name of the shared library to open or a sequence of filenames to try and open.
  2. use_cdecl : an integer, if non-zero, then force all routines in this library to be declared as CDECL instead of STDCALL

Returns

An atom, actually a 32-bit address. 0 is returned if the library cannot be loaded.

Comments

The use_cdecl flag only applies to Windows. Setting it on other platforms has no effect.

By default, open_dll will crash your application if it cannot load a library. See Errors and debugging for more details.

See also: define_c_var, define_c_func, define_c_proc, c_func, c_proc