<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en" dir="ltr">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
<link rel="stylesheet" href="../../style.css">
<title>
Gambas Documentation - External Function Declaration
</title>
</head>
<table class="none" width="100%" cellpadding="0" cellspacing="0" border="0">
<tr><td align="left">
<font size="-1">
<a href="../../help+en"><img class="flag" alt="Home" border="0" src="../../img/lang/en.png" align="center"></a>&nbsp;
<a href="../lang+en">Up</a>&nbsp;
<a href="export+en">Previous</a>&nbsp;
<a href="extern+en">Next</a>&nbsp;
</td></tr></table>
<div class="notab">
<h1>
External Function Declaration
</h1>
<div class="black"><font size="-2"><b>Syntax</b></font></div>
<pre class="syntax">{ <b>PUBLIC</b> | <b>PRIVATE</b> } <b>EXTERN</b>
&nbsp;&nbsp;<u>Identifier</u>
&nbsp;&nbsp;<b>(</b>
&nbsp;&nbsp;&nbsp;&nbsp;[ <u>Parameter</u> <b>AS</b> <u>Datatype</u> [ <b>,</b> ... ] ]
&nbsp;&nbsp;<b>)</b>
&nbsp;&nbsp;[ <b>AS</b> <u>Datatype</u> ]
&nbsp;&nbsp;[ <b>IN</b> <u>Library</u> ] [ <b>EXEC</b> <u>Alias</u> ]</pre><p>

This declares an external function located in a system shared library.
<p>
<h2>Arguments</h2>
<p>
The parameters of an extern function can be of any <a href="../def/gambas+en">Gambas</a> datatypes, except <a href="type/variant+en">Variant</a>.
<a href="../def/gambas+en">Gambas</a> will automatically marshall its datatypes to the internal machine ones.
<p>
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.
<p>
For any pointer argument, use the <a href="type/pointer+en">Pointer</a> datatype.
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/warning.png" align="center"></td><td valign="top">
You can use <a href="../comp/gb/string+en">String</a> arguments, unless the function modifies it, because in <a href="../def/gambas+en">Gambas</a> <a href="../comp/gb/string+en">String</a> values
can be shared.
</td></tr></table></div>
<p>
<h2>Return Value</h2>
<p>
The return value of an extern function can be of any <a href="../def/gambas+en">Gambas</a> datatypes,
except <a href="type/object+en">Object</a> and <a href="type/variant+en">Variant</a>.
<p>
<div class="warning"><table class="none" border="0"><tr><td width="40" valign="top"><img border="0" src="../../img/warning.png" align="center"></td><td valign="top">
If an extern function returns a string, then <a href="../def/gambas+en">Gambas</a> will return a copy of it.
<p>
If you need the real string returned by the function, use the <a href="type/pointer+en">Pointer</a> datatype and the
<a href="strptr+en">StrPtr</a> function.
</td></tr></table></div>
<p>
<h2>Library name</h2>
<p>
The name of the library is specified with the <u>Library</u> argument. If you don't specify it,
then the name of the one specified with the last <tt><b><a href="library+en">LIBRARY</a></b></tt> declaration is used.
<p>
The name of the library must be the name of its file without any extension and version number.
<p>
For example, if you want to use the OpenGL library named <tt>libGL.so.1</tt> on your system, the name to
use with <a href="../def/gambas+en">Gambas</a> is <tt>&quot;libGL&quot;</tt>.
<p>
If you need to specify a specific version number of the library (the numbers after the <tt>.so</tt>
extension on <a href="../def/linux+en">Linux</a>), you can add it after the library name, by using a colon separator.
<p>
For example, if you need specifically the 1.0.7667 version of the OpenGL library, you will specify
the following library name: <tt>&quot;libGL:1.0.7667&quot;</tt>.
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' I need to do some ioctl's!
EXTERN ioctl(fd AS Integer, op AS Integer, arg AS Pointer) AS Integer IN &quot;libc:6&quot;

...

Err = ioctl(MyStream.Handle, ... )</pre>
<p>
<h2>Function name</h2>
<p>
The name of the function in the library is by default the name of the function in <a href="../def/gambas+en">Gambas</a>,
i.e. <u><a href="../def/identifier+en">identifier</a></u>.
<p>
If it is impossible, or not desirable, you can specify the true
library function name with the <tt><b>EXEC</b></tt> keyword.
<p>
<div class="gray"><font size="-2"><b>Example</b></font></div>
<pre class="example">' This function name is already a Gambas reserved word!
EXTERN SysOpen(Name AS String, Flags AS Integer, Mode AS Integer) AS Integer IN &quot;libc:6&quot; EXEC &quot;open&quot;</pre>
<p>
<hr><b>See also</b><br>
<a href="../cat/extern+en">External Function Management</a>&nbsp;

</div>
</body>
</html>

