/usr/lib/swi-prolog/doc/Manual/DLL.html

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN" "http://www.w3.org/TR/html4/strict.dtd">

<HTML>
<HEAD>
<TITLE>SWI-Prolog 5.7.11 Reference Manual: Section 9.4</TITLE><LINK REL=home HREF="index.html">
<LINK REL=contents HREF="Contents.html">
<LINK REL=index HREF="DocIndex.html">
<LINK REL=previous HREF="dynstatic.html">
<LINK REL=next HREF="foreigntypes.html">
<STYLE type="text/css">
/* Style sheet for SWI-Prolog latex2html
*/

dd.defbody
{ margin-bottom: 1em;
}

dt.pubdef
{ background-color: #c5e1ff;
}

.bib dd
{ margin-bottom: 1em;
}

.bib dt
{ float: left;
margin-right: 1.3ex;
}

pre.code
{ margin-left: 1.5em;
margin-right: 1.5em;
border: 1px dotted;
padding-top: 5px;
padding-left: 5px;
padding-bottom: 5px;
background-color: #f8f8f8;
}

div.navigate
{ text-align: center;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
}

div.title
{ text-align: center;
padding-bottom: 1em;
font-size: 200%;
font-weight: bold;
}

div.author
{ text-align: center;
font-style: italic;
}

div.abstract
{ margin-top: 2em;
background-color: #f0f0f0;
border: 1px dotted;
padding: 5px;
margin-left: 10%; margin-right:10%;
}

div.abstract-title
{ text-align: center;
padding: 5px;
font-size: 120%;
font-weight: bold;
}

div.toc-h1
{ font-size: 200%;
font-weight: bold;
}

div.toc-h2
{ font-size: 120%;
font-weight: bold;
margin-left: 2em;
}

div.toc-h3
{ font-size: 100%;
font-weight: bold;
margin-left: 4em;
}

div.toc-h4
{ font-size: 100%;
margin-left: 6em;
}

span.sec-nr
{ 
}

span.sec-title
{ 
}

span.pred-ext
{ font-weight: bold;
}

span.pred-tag
{ float: right;
font-size: 80%;
font-style: italic;
color: #202020;
}

/* Footnotes */

sup.fn { color: blue; text-decoration: underline; }
span.fn-text { display: none; }
sup.fn span {display: none;}
sup:hover span 
{ display: block !important;
position: absolute; top: auto; left: auto; width: 80%;
color: #000; background: white;
border: 2px solid;
padding: 5px; margin: 10px; z-index: 100;
font-size: smaller;
}
</STYLE>
</HEAD>
<BODY BGCOLOR="white">
<DIV class="navigate"><A class="nav" href="index.html"><IMG SRC="home.gif" BORDER=0 ALT="Home"></A>
<A class="nav" href="Contents.html"><IMG SRC="index.gif" BORDER=0 ALT="Contents"></A>
<A class="nav" href="DocIndex.html"><IMG SRC="yellow_pages.gif" BORDER=0 ALT="Index"></A>
<A class="nav" href="dynstatic.html"><IMG SRC="prev.gif" BORDER=0 ALT="Previous"></A>
<A class="nav" href="foreigntypes.html"><IMG SRC="next.gif" BORDER=0 ALT="Next"></A>
</DIV>

<H2><A NAME="sec:9.4"><SPAN class="sec-nr">9.4</SPAN> <SPAN class="sec-title">Using 
the library shlib for <CODE>.DLL</CODE> and <CODE>.so</CODE> files</SPAN></A></H2>

<A NAME="sec:DLL"></A>
<A NAME="sec:shlib"></A>

<P>This section discusses the functionality of the (autoload) library
<CODE>shlib.pl</CODE>, providing an interface to shared libraries. This 
library can only be used if the Prolog flag <A class="flag" href="flags.html#flag:open_shared_object">open_shared_object</A> 
is enabled.

<DL>
<DT class="pubdef"><A NAME="load_foreign_library/2"><STRONG>load_foreign_library</STRONG>(<VAR>+Lib, 
+Entry</VAR>)</A></DT>
<DD class="defbody">
Search for the given foreign library and link it to the current 
SWI-Prolog instance. The library may be specified with or without the 
extension. First, <A NAME="idx:absolutefilename3:1386"></A><A class="pred" href="files.html#absolute_file_name/3">absolute_file_name/3</A> 
is used to locate the file. If this succeeds, the full path is passed to 
the low-level function to open the library. Otherwise, the plain library 
name is passed, exploiting the operating-system defined search mechanism 
for the shared library. The <A NAME="idx:filesearchpath2:1387"></A><A class="pred" href="consulting.html#file_search_path/2">file_search_path/2</A> 
alias mechanism defines the alias <CODE>foreign</CODE>, which refers to 
the directories <CODE>&lt;<VAR>plhome</VAR>&gt;/lib/&lt;<VAR>arch</VAR>&gt;</CODE> 
and
<CODE>&lt;<VAR>plhome</VAR>&gt;/lib</CODE>, in this order.

<P>If the library can be loaded, the function called <VAR>Entry</VAR> 
will be called without arguments. The return value of the function is 
ignored.

<P>The <VAR>Entry</VAR> function will normally call 
PL_register_foreign() to declare functions in the library as foreign 
predicates.
</DD>
<DT class="pubdef"><A NAME="load_foreign_library/1"><STRONG>load_foreign_library</STRONG>(<VAR>+Lib</VAR>)</A></DT>
<DD class="defbody">
Equivalent to <A NAME="idx:loadforeignlibrary2:1388"></A><A class="pred" href="DLL.html#load_foreign_library/2">load_foreign_library/2</A>. 
For the entry-point, this function first identifies the `base-name' of 
the library, which is defined to be the file-name with path nor 
extension. It will then try the entry-point
<CODE>install-</CODE>&lt;<VAR>base</VAR>&gt;. On failure it will try to 
function install(). Otherwise no install function will be called.
</DD>
<DT class="pubdef"><A NAME="unload_foreign_library/1"><STRONG>unload_foreign_library</STRONG>(<VAR>+Lib</VAR>)</A></DT>
<DD class="defbody">
If the foreign library defines the function uninstall_&lt;<VAR>base</VAR>&gt;() 
or uninstall(), this function will be called without arguments and its 
return value is ignored. Next, <A NAME="idx:abolish2:1389"></A><A class="pred" href="db.html#abolish/2">abolish/2</A> 
is used to remove all known foreign predicates defined in the library. 
Finally the library itself is detached from the process.
</DD>
<DT class="pubdef"><A NAME="current_foreign_library/2"><STRONG>current_foreign_library</STRONG>(<VAR>-Lib, 
-Predicates</VAR>)</A></DT>
<DD class="defbody">
Query the currently loaded foreign libraries and their predicates. <EM>Predicates</EM> 
is a list with elements of the form <EM>Module:Head</EM>, indicating the 
predicates installed with PL_register_foreign() when the entry-point of 
the library was called.
</DD>
</DL>

<P><A class="fig" href="DLL.html#fig:msgbox">Figure 6</A> connects a 
Windows message-box using a foreign function. This example was tested 
using Windows&nbsp;NT and Microsoft Visual C++ 2.0.

<PRE class="code">
#include &lt;windows.h&gt;
#include &lt;SWI-Prolog.h&gt;

static foreign_t
pl_say_hello(term_t to)
{ char *a;

  if ( PL_get_atom_chars(to, &amp;a) )
  { MessageBox(NULL, a, "DLL test", MB_OK|MB_TASKMODAL);

    PL_succeed;
  }

  PL_fail;
}

install_t
install()
{ PL_register_foreign("say_hello", 1, pl_say_hello, 0);
}
</PRE>

<TABLE ALIGN=center WIDTH="75%"><TR><TD>
<B>Figure 6 : </B>MessageBox() example in Windows&nbsp;NT</TABLE>

<A NAME="fig:msgbox"></A>

<H3><A NAME="sec:9.4.1"><SPAN class="sec-nr">9.4.1</SPAN> <SPAN class="sec-title">Static 
Linking</SPAN></A></H3>

<A NAME="sec:staticl"></A>

<P>Below is an outline of the files structure required for statically 
linking SWI-Prolog with foreign extensions. <CODE>\ldots/pl</CODE> 
refers to the SWI-Prolog home directory (see the Prolog flag <A class="flag" href="flags.html#flag:home">home</A>).
<CODE>&lt;<VAR>arch</VAR>&gt;</CODE> refers to the architecture 
identifier that may be obtained using the Prolog flag <A class="flag" href="flags.html#flag:arch">arch</A>.

<P>
<CENTER>
<TABLE BORDER=0 FRAME=void RULES=groups>
<TR VALIGN=top><TD><CODE>.../pl/runtime/&lt;<VAR>arch</VAR>&gt;/libpl.a</CODE> </TD><TD>SWI-Library </TD></TR>
<TR VALIGN=top><TD><CODE>.../pl/include/SWI-Prolog.h</CODE> </TD><TD>Include 
file </TD></TR>
<TR VALIGN=top><TD><CODE>.../pl/include/SWI-Stream.h</CODE> </TD><TD>Stream 
I/O include file </TD></TR>
<TR VALIGN=top><TD><CODE>.../pl/include/SWI-Exports</CODE> </TD><TD>Export 
declarations (AIX only) </TD></TR>
<TR VALIGN=top><TD><CODE>.../pl/include/stub.c</CODE> </TD><TD>Extension 
stub</TD></TR>
</TABLE>

</CENTER>

<P>The definition of the foreign predicates is the same as for dynamic 
linking. Unlike with dynamic linking however, there is no initialisation 
function. Instead, the file <CODE>\ldots/pl/include/stub.c</CODE> may be 
copied to your project and modified to define the foreign extensions. 
Below is stub.c, modified to link the lowercase example described later 
in this chapter:

<PRE class="code">
#include &lt;stdio.h&gt;
#include &lt;SWI-Prolog.h&gt;

extern foreign_t pl_lowercase(term, term);

PL_extension predicates[] =
{
/*{ "name",      arity,  function,      PL_FA_&lt;flags&gt; },*/

  { "lowercase", 2       pl_lowercase,  0 },
  { NULL,        0,      NULL,          0 }     /* terminating line */
};


int
main(int argc, char **argv)
{ PL_register_extensions(predicates);

  if ( !PL_initialise(argc, argv) )
    PL_halt(1);

  PL_install_readline();                /* delete if not required */

  PL_halt(PL_toplevel() ? 0 : 1);
}
</PRE>

<P>Now, a new executable may be created by compiling this file and 
linking it to <CODE>libpl.a</CODE> from the runtime directory and the 
libraries required by both the extensions and the SWI-Prolog kernel. 
This may be done by hand, or using the <B>plld</B> utility described in 
secrefplld. If the linking is performed `by hand', the command-line 
option <CODE>-dump-runtime-variables</CODE> (see <A class="sec" href="cmdline.html">section 
2.4</A>) can be used to obtain the required paths, libraries and linking 
options to link the new executable.

<P></BODY></HTML>
swi-prolog-nox 5.10.4-3ubuntu1 / usr / lib / swi-prolog / doc / Manual / DLL.html
