doc/ref_func_libr.xml

   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.inc">
   5 %myents;
   6 ]>
   7
   8 <reference id="func_libr">
   9       <title>Functions &amp; Libraries</title>
  10
  11       <refentry id="def-function">
  12         <refnamediv>
  13           <refname>def-function</refname>
  14         <refpurpose>Declares a function.
  15         </refpurpose>
  16         <refclass>Macro</refclass>
  17       </refnamediv>
  18       <refsynopsisdiv>
  19         <title>Syntax</title>
  20         <synopsis>
  21           <function>def-function</function> <replaceable>name args &amp;key module returning</replaceable>
  22         </synopsis>
  23       </refsynopsisdiv>
  24       <refsect1>
  25         <title>Arguments and Values</title>
  26         <variablelist>
  27           <varlistentry>
  28             <term><parameter>name</parameter></term>
  29             <listitem>
  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.
  31               </para>
  32             </listitem>
  33           </varlistentry>
  34           <varlistentry>
  35             <term><parameter>args</parameter></term>
  36             <listitem>
  37               <para>A list of argument declarations. If &nil;, indicates that the function does not take any arguments.
  38               </para>
  39             </listitem>
  40           </varlistentry>
  41           <varlistentry>
  42             <term><parameter>module</parameter></term>
  43             <listitem>
  44               <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
  45             </listitem>
  46           </varlistentry>
  47           <varlistentry>
  48             <term><returnvalue>returning</returnvalue></term>
  49             <listitem>
  50               <para>A declaration specifying the result type of the
  51 foreign function. If <constant>:void</constant> indicates module does not return any value.
  52               </para>
  53             </listitem>
  54           </varlistentry>
  55         </variablelist>
  56       </refsect1>
  57       <refsect1>
  58         <title>Description</title>
  59         <para>Declares a foreign function.
  60         </para>
  61       </refsect1>
  62       <refsect1>
  63         <title>Examples</title>
  64         <screen>
  65 (def-function "gethostname"
  66   ((name (* :unsigned-char))
  67    (len :int))
  68   :returning :int)
  69         </screen>
  70       </refsect1>
  71       <refsect1>
  72         <title>Side Effects</title>
  73         <para>None.</para>
  74       </refsect1>
  75       <refsect1>
  76         <title>Affected by</title>
  77         <para>None.</para>
  78       </refsect1>
  79       <refsect1>
  80         <title>Exceptional Situations</title>
  81         <para>None.</para>
  82       </refsect1>
  83     </refentry>
  84
  85       <refentry id="load-foreign-library">
  86         <refnamediv>
  87           <refname>load-foreign-library</refname>
  88         <refpurpose>Loads a foreign library.
  89         </refpurpose>
  90         <refclass>Function</refclass>
  91       </refnamediv>
  92       <refsect1>
  93         <title>Syntax</title>
  94 <synopsis>
  95           <function>load-foreign-library</function> <replaceable>filename &amp;key module supporting-libraries force-load</replaceable> => <returnvalue>success</returnvalue>
  96 </synopsis>
  97       </refsect1>
  98       <refsect1>
  99         <title>Arguments and Values</title>
 100         <variablelist>
 101           <varlistentry>
 102             <term><parameter>filename</parameter></term>
 103             <listitem>
 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.
 107               </para>
 108             </listitem>
 109           </varlistentry>
 110           <varlistentry>
 111             <term><parameter>module</parameter></term>
 112             <listitem>
 113               <para>A string designating the name of the module to apply
 114 to functions in this library. (Required for Lispworks)
 115               </para>
 116             </listitem>
 117           </varlistentry>
 118           <varlistentry>
 119             <term><parameter>supporting-libraries</parameter></term>
 120             <listitem>
 121               <para>A list of strings naming the libraries required to
 122 link the foreign library. (Required by CMUCL)
 123               </para>
 124             </listitem>
 125           </varlistentry>
 126           <varlistentry>
 127             <term><parameter>force-load</parameter></term>
 128             <listitem>
 129               <para>Forces the loading of the library if it has been previously loaded.
 130               </para>
 131             </listitem>
 132           </varlistentry>
 133           <varlistentry>
 134             <term><returnvalue>success</returnvalue></term>
 135             <listitem>
 136               <para>A boolean flag, &t; if the library was able to be
 137 loaded successfully or if the library has been previously loaded,
 138 otherwise &nil;.
 139               </para>
 140             </listitem>
 141           </varlistentry>
 142         </variablelist>
 143       </refsect1>
 144       <refsect1>
 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.
 149         </para>
 150       </refsect1>
 151       <refsect1>
 152         <title>Examples</title>
 153         <screen>
 154   (load-foreign-library #p"/usr/lib/libmysqlclient.so"
 155                         :module "mysql"
 156                         :supporting-libraries '("c"))
 157     => T
 158         </screen>
 159       </refsect1>
 160       <refsect1>
 161         <title>Side Effects</title>
 162         <para>Loads the foreign code into the Lisp system.
 163         </para>
 164       </refsect1>
 165       <refsect1>
 166         <title>Affected by</title>
 167         <para>Ability to load the file.</para>
 168       </refsect1>
 169       <refsect1>
 170         <title>Exceptional Situations</title>
 171         <para>None.</para>
 172       </refsect1>
 173     </refentry>
 174
 175       <refentry id="find-foreign-library">
 176         <refnamediv>
 177           <refname>find-foreign-library</refname>
 178         <refpurpose>Finds a foreign library file.
 179         </refpurpose>
 180         <refclass>Function</refclass>
 181       </refnamediv>
 182       <refsect1>
 183         <title>Syntax</title>
 184 <synopsis>
 185           <function>find-foreign-library</function> <replaceable>names directories &amp; drive-letters types</replaceable> => <returnvalue>path</returnvalue>
 186 </synopsis>
 187       </refsect1>
 188       <refsect1>
 189         <title>Arguments and Values</title>
 190         <variablelist>
 191           <varlistentry>
 192             <term><parameter>names</parameter></term>
 193             <listitem>
 194               <para>A string or list of strings containing the base name of the library file.
 195               </para>
 196             </listitem>
 197           </varlistentry>
 198           <varlistentry>
 199             <term><parameter>directories</parameter></term>
 200             <listitem>
 201               <para>A string or list of strings containing the directory the library file.
 202               </para>
 203             </listitem>
 204           </varlistentry>
 205           <varlistentry>
 206             <term><parameter>drive-letters</parameter></term>
 207             <listitem>
 208               <para>A string or list of strings containing the drive letters for the library file.
 209               </para>
 210             </listitem>
 211           </varlistentry>
 212           <varlistentry>
 213             <term><parameter>types</parameter></term>
 214             <listitem>
 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.
 217               </para>
 218             </listitem>
 219           </varlistentry>
 220           <varlistentry>
 221             <term><returnvalue>path</returnvalue></term>
 222             <listitem>
 223               <para>A path containing the path found, or &nil; if the library file was not found.
 224               </para>
 225             </listitem>
 226           </varlistentry>
 227         </variablelist>
 228       </refsect1>
 229       <refsect1>
 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.
 233         </para>
 234       </refsect1>
 235       <refsect1>
 236         <title>Examples</title>
 237         <screen>
 238 (find-foreign-library '("libmysqlclient" "libmysql")
 239     '("/opt/mysql/lib/mysql/" "/usr/local/lib/" "/usr/lib/" "/mysql/lib/opt/")
 240     :types '("so" "dll")
 241     :drive-letters '("C" "D" "E"))
 242 => #P"D:\\mysql\\lib\\opt\\libmysql.dll"
 243         </screen>
 244       </refsect1>
 245       <refsect1>
 246         <title>Side Effects</title>
 247         <para>None.
 248         </para>
 249       </refsect1>
 250       <refsect1>
 251         <title>Affected by</title>
 252         <para>None.</para>
 253       </refsect1>
 254       <refsect1>
 255         <title>Exceptional Situations</title>
 256         <para>None.</para>
 257       </refsect1>
 258     </refentry>
 259
 260 </reference>
 261
 262