{ 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 in the next 3.0 version, and only for non-string arguments.

So, in Gambas 2.x, you must do this way:

' The following function are declared this way in C:
' void GetAString(char **result, char *a, char *b);
' void GetAFloat(double *result, double a, double b);

EXTERN SUB GetAString(Result AS Pointer, A AS String, B AS String)
EXTERN SUB GetAFloat(Result AS Pointer, A AS Float, B AS Float)

DIM pResult AS Pointer
DIM sResult AS String
DIM fResult AS Float

pResult = Alloc(4) ' The size of a pointer, on a 32 bits architecture
GetAString(pResult, "Hello", "World")
sResult = StrPtr(pValue)
Free(pResult)

pResult = Alloc(8) ' The size of a Float value
GetAFloat(pResult, Pi, Pi(2))
READ #pResult, fResult
Free(pResult)

3.0

In Gambas 3, the second case will be simpler: EXTERN SUB GetAFloat(Result AS Pointer, A AS Float, B AS Float) DIM fResult AS Float GetAFloat(VarPtr(fResult), Pi, Pi(2))

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.

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.

' 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"