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