External Function Declaration
{ PUBLIC | PRIVATE } EXTERN
Identifier
(
[ Parameter AS Datatype [ , ... ] ]
)
[ AS Datatype ]
[ IN Library ] [ EXEC Alias ]
This declares an external function located in a system shared library.
Arguments
The parameters of an extern function can be of any Gambas datatypes, except
Variant.
Gambas will automatically marshall its datatypes to the internal machine ones.
When passing an object, the function receives a pointer to its data. If the object is a class, then the
function receives a pointer to the static data of the class.
For any pointer argument, use the
Pointer datatype.
You can use
String arguments, unless the function modifies it, because in Gambas
String values
are shared constants.
Pointer arguments
If you must send a pointer to a variable, you can use the
VarPtr function, but only for non-string arguments.
Examples
EXTERN GetAFloat(Result AS Pointer, A AS Float, B AS Float)
DIM fResult AS Float
GetAFloat(VarPtr(fResult), Pi, Pi(2))
Use
Pointer too when the extern function argument is a memory size type (for example
size_t), because these types have the same integer size as a
void *.
Function Callbacks
Some extern functions may take a function pointer as argument, this function pointer being used as a callback.
To use a Gambas function as a callback:
-
Just declare the function pointer argument as
Pointer in the extern function declaration.
-
Use the Gambas function name as extern function argument.
Example
Private Extern qsort(base As Pointer, nmemb As Pointer, size As Pointer, compar As Pointer) In "libc:6"
Private Sub Compare(pA As Pointer, pB As Pointer) As Integer
...
End
Public Sub Main()
Dim aVal As Integer[]
...
qsort(aVal.Data, aVal.Count, 4, Compare)
...
End
Note that you can use any private or public Gambas function. You can even use
non-static methods: but beware that the object the method applies on is
captured by the callback, and released at the end of the program only.
Return Value
The return value of an extern function can be of any Gambas datatypes,
except
Object and
Variant.
If an extern function returns a string, then Gambas will return a copy of it.
If you need the real string returned by the function, use the
Pointer datatype and the
StrPtr function.
If an error code is returned by the call, it will be in
System.Error.
Library name
The name of the library is specified with the
Library argument. If you don't specify it,
then the name of the one specified with the last
LIBRARY declaration is used.
The name of the library must be the name of its file without any extension and version number.
For example, if you want to use the OpenGL library named
libGL.so.1 on your system, the name to
use with Gambas is
"libGL".
If you need to specify a specific version number of the library (the numbers after the
.so
extension on Linux), you can add it after the library name, by using a colon separator.
For example, if you need specifically the 1.0.7667 version of the OpenGL library, you will specify
the following library name:
"libGL:1.0.7667".
Examples
' I need to do some ioctl's!
EXTERN ioctl(fd AS Integer, op AS Integer, arg AS Pointer) AS Integer IN "libc:6"
...
Err = ioctl(MyStream.Handle, ... )
Function name
The name of the function in the library is by default the name of the function in Gambas,
i.e.
identifier.
If it is impossible, or not desirable, you can specify the true
library function name with the
EXEC keyword.
Examples
' This function name is already a Gambas reserved word!
EXTERN SysOpen(Name AS String, Flags AS Integer, Mode AS Integer) AS Integer IN "libc:6" EXEC "open"
See also