1 <?xml version="1.0" encoding="utf-8"?>
2 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd" [
4 <!ENTITY % myents SYSTEM "entities.xml">
8 <reference id="func_libr">
9 <title>Functions & Libraries</title>
11 <refentry id="def-function">
13 <refname>def-function</refname>
14 <refpurpose>Declares a function.
16 <refclass>Macro</refclass>
21 <function>def-function</function> <replaceable>name args &key module returning</replaceable>
25 <title>Arguments and Values</title>
28 <term><parameter>name</parameter></term>
30 <para>A string or list specificying the function name. If it is a string, that names the foreign function. A Lisp name is created by translating #\_ to #\- and by converting to upper-case in case-insensitive Lisp implementations. If it is a list, the first item is a string specifying the foreign function name and the second it is a symbol stating the Lisp name.
35 <term><parameter>args</parameter></term>
37 <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
42 <term><parameter>module</parameter></term>
44 <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
48 <term><returnvalue>returning</returnvalue></term>
50 <para>A declaration specifying the result type of the
51 foreign function. If <constant>:void</constant> indicates module does not return any value.
58 <title>Description</title>
59 <para>Declares a foreign function.
63 <title>Examples</title>
65 (def-function "gethostname"
66 ((name (* :unsigned-char))
72 <title>Side Effects</title>
76 <title>Affected by</title>
80 <title>Exceptional Situations</title>
85 <refentry id="load-foreign-library">
87 <refname>load-foreign-library</refname>
88 <refpurpose>Loads a foreign library.
90 <refclass>Function</refclass>
95 <function>load-foreign-library</function> <replaceable>filename &key module supporting-libraries force-load</replaceable> => <returnvalue>success</returnvalue>
99 <title>Arguments and Values</title>
102 <term><parameter>filename</parameter></term>
104 <para>A string or pathname specifying the library location
105 in the filesystem. At least one implementation (&lw;) can not
106 accept a logical pathname.
111 <term><parameter>module</parameter></term>
113 <para>A string designating the name of the module to apply
114 to functions in this library. (Required for Lispworks)
119 <term><parameter>supporting-libraries</parameter></term>
121 <para>A list of strings naming the libraries required to
122 link the foreign library. (Required by CMUCL)
127 <term><parameter>force-load</parameter></term>
129 <para>Forces the loading of the library if it has been previously loaded.
134 <term><returnvalue>success</returnvalue></term>
136 <para>A boolean flag, &t; if the library was able to be
137 loaded successfully or if the library has been previously loaded,
145 <title>Description</title>
146 <para>Loads a foreign library. Applies a module name to functions
147 within the library. Ensures that a library is only loaded once during
148 a session. A library can be reloaded by using the <symbol>:force-load</symbol> key.
152 <title>Examples</title>
154 (load-foreign-library #p"/usr/lib/libmysqlclient.so"
156 :supporting-libraries '("c"))
161 <title>Side Effects</title>
162 <para>Loads the foreign code into the Lisp system.
166 <title>Affected by</title>
167 <para>Ability to load the file.</para>
170 <title>Exceptional Situations</title>
175 <refentry id="find-foreign-library">
177 <refname>find-foreign-library</refname>
178 <refpurpose>Finds a foreign library file.
180 <refclass>Function</refclass>
183 <title>Syntax</title>
185 <function>find-foreign-library</function> <replaceable>names directories & drive-letters types</replaceable> => <returnvalue>path</returnvalue>
189 <title>Arguments and Values</title>
192 <term><parameter>names</parameter></term>
194 <para>A string or list of strings containing the base name of the library file.
199 <term><parameter>directories</parameter></term>
201 <para>A string or list of strings containing the directory the library file.
206 <term><parameter>drive-letters</parameter></term>
208 <para>A string or list of strings containing the drive letters for the library file.
213 <term><parameter>types</parameter></term>
215 <para>A string or list of strings containing the file type of the library file. Default
216 is &nil;. If &nil;, will use a default type based on the currently running implementation.
221 <term><returnvalue>path</returnvalue></term>
223 <para>A path containing the path found, or &nil; if the library file was not found.
230 <title>Description</title>
231 <para>Finds a foreign library by searching through a number of possible locations. Returns
232 the path of the first found file.
236 <title>Examples</title>
238 (find-foreign-library '("libmysqlclient" "libmysql")
239 '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
241 :drive-letters '("C" "D" "E"))
242 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
246 <title>Side Effects</title>
251 <title>Affected by</title>
255 <title>Exceptional Situations</title>