Linking to external code
Using dynamic libraries and C routines with Euphoria
include adv/dll.e
Functions/Procedures
Subtopics
Linking to external code
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
Category:
Linking to external code
Returns the routine id of the given callback address.
See also: callback, callback_id
Linking to external code
Category:
Linking to external code
Get a machine address for an Euphoria procedure.
- Parameters
- 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
- rid : an integer, a routine id from define_c_func or define_c_proc.
- 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
- lib : an object, either an entry point returned by open_dll, or "" to denote a routine
in memory.
- routine_name : an object, either the name of a function in the shared library or the
memory address of the machine-code routine.
- arg_types : a sequence, a list of C Type constants for each argument.
- 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
- lib : an atom, the address of the shared library from open_dll
- 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
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
- file_name : a sequence, the name of the shared library to open or a sequence of filenames
to try and open.
- 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