/ lang / extdecl
External Function Declaration
Syntax

    { 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.

If you must send a pointer to a variable, use the VarPtr function.

| You can use String arguments, unless the function modifies it, because in Gambas String values are shared constants.

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

### See also

External Function Management