</para>
</sect2>
- <sect2 id="uffi-declare">
- <title>uffi-declare</title>
- <para>
- This is used wherever a <function>declare</function>
- expression can be placed. For example:
- </para>
- <para>
- <programlisting>
-(let ((my-structure (uffi:allocate-foreign-object 'a-struct)))
- (uffi:uffi-declare a-struct my-structure))
- </programlisting>
- </para>
- </sect2>
-
- <sect2 id="slot-type">
- <title>slot-type</title>
+ <sect2 id="def-type">
+ <title>def-type</title>
<para>
- This is used inside of <function>defclass</function> and
- <function>defstruct</function> expressions to set the type
- for a field. Because the type identifier is not evaluated in
- &cl;, the expression must be backquoted for effect. For
- example:
- </para>
+ This is used wherever a &cl; <function>deftype</function>
+ expression can be placed. Used to declare types to
+the compiler for optimization. Currently, on &cmucl; takes advantage
+of this. </para>
<para>
<programlisting>
-(eval
- `(defclass a-class ()
- ((char-ptr :type ,(uffi:slot-type (* :char))))))
+(uffi:def-type my-struct-def my-struct-foreign-type)
</programlisting>
</para>
</sect2>
</sect1>
<sect1>
- <title>Immediate Types</title>
+ <title>Primitive Types</title>
<sect2>
<title>Overview</title>
<para>
- Immediate types have a single value, these include
+ Primitive types have a single value, these include
characters, numbers, and pointers. They are all symbols in
the keyword package.
</para>
<itemizedlist>
- <listitem>
- <para><constant>:byte</constant> - Unsigned 8-bit</para>
- </listitem>
<listitem>
<para><constant>:char</constant> - Signed 8-bits</para>
</listitem>
<para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
</listitem>
<listitem>
- <para><constant>:single-float</constant> - 32-bit floating point</para>
+ <para><constant>:float</constant> - 32-bit floating point</para>
</listitem>
<listitem>
- <para><constant>:double-float</constant> - 64-bit floating point</para>
+ <para><constant>:double</constant> - 64-bit floating point</para>
</listitem>
<listitem>
- <para>
- <constant>
- :cstring
- </constant>
- - A null-terminated string used for passing and returning with a function.
- </para>
+ <para><constant>:cstring</constant> -
+A null-terminated string used for passing and returning with a function.
+ </para>
</listitem>
<listitem>
- <para>
- <constant>
- :void
- </constant>
- - An absence of a value. Used in generic pointers and in
- return types from functions.</para>
+ <para><constant>:void</constant> -
+The absence of a value. Used in generic pointers and in return types from functions.</para>
</listitem>
<listitem>
<para><constant>*</constant> - Used to declare a pointer to an object</para>
<sect1>
<title>Objects</title>
+ <sect2>
+ <title>Overview</title>
+ <para>
+ Objects are entities that can allocated and freed.
+ </para>
+ </sect2>
<sect2>
<title>allocate-foreign-object</title>
<para>
<title>convert-to-cstring</title>
<para>
Converts a Lisp string to a
- <varname>cstring</varname>. These
- <varname>cstring's</varname> should be freed with
+ <varname>cstring</varname>. The
+ <varname>cstring</varname> should be freed with
<function>free-cstring</function>.
</para>
</sect2>
<para>
Binds a lexical variable to a newly allocated <varname>cstring</varname>. Automatically frees <varname>cstring</varname>.
</para>
+ <sect3>
+ <title>Examples</title>
+ <para>
+ <programlisting>
+(def-function ("getenv" c-getenv)
+ ((name :cstring))
+ :returning :cstring)
+
+(defun getenv (key)
+ "Returns an environment variable, or NIL if it does not exist"
+ (check-type key string)
+ (with-cstring (key-cstring key)
+ (convert-from-cstring (c-getenv key-cstring))))
+ </programlisting>
+ </para>
+ </sect3>
</sect2>
<sect2>
- <title>covert-from-foreign-string</title>
+ <title>convert-from-foreign-string</title>
<para>
Returns a Lisp string from a foreign string. Has parameters
to handle ASCII versus binary strings.
<sect1>
<title>Functions</title>
- <sect2>
- <title>def-function</title>
- <para>
- This macro generates a &c; function definition.
- </para>
- </sect2>
+ <refentry id="def-function">
+ <refnamediv>
+ <refname>def-function</refname>
+ <refpurpose>Declares a function.
+ </refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <title>Syntax</title>
+ <synopsis>
+ <function>def-function</function> <replaceable>name args &key module returning</replaceable>
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>name</parameter></term>
+ <listitem>
+ <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.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>args</parameter></term>
+ <listitem>
+ <para>A list of argument declarations. Use &nil; to specify no arguments.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>module</parameter></term>
+ <listitem>
+ <para>A string specifying which module (or library) that the foreign function resides. (Required by Lispworks)</para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>returning</returnvalue></term>
+ <listitem>
+ <para>A declaration specifying the result type of the
+foreign function.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>Declares a foreign function.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <programlisting>
+(def-function "gethostname"
+ ((name :cstring)
+ (len :int))
+ :returning :int)
+ </programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>None.</para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>None.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
</sect1>
<sect1>
<title>Libraries</title>
- <sect2>
- <title>load-foreign-library</title>
- <para>
- This function loads foreign libraries. It has checks to
- ensure that a library is loaded only once during a session.
- </para>
- </sect2>
- </sect1>
-
+ <refentry id="load-foreign-library">
+ <refnamediv>
+ <refname>load-foreign-library</refname>
+ <refpurpose>Loads a foreign library.
+ </refpurpose>
+ <refclass>Function</refclass>
+ </refnamediv>
+ <refsect1>
+ <title>Syntax</title>
+<synopsis>
+ <function>load-foreign-library</function> <replaceable>filename &key module supporting-libraries</replaceable> => <returnvalue>success</returnvalue>
+</synopsis>
+ </refsect1>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>filename</parameter></term>
+ <listitem>
+ <para>A string or pathname specifying the library location
+in the filesystem. At least one implementation (&lw;) can not
+accept a logical pathname.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>module</parameter></term>
+ <listitem>
+ <para>A string designating the name of the module to apply
+to functions in this library. (Required for Lispworks)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>supporting-libraries</parameter></term>
+ <listitem>
+ <para>A list of strings naming the libraries required to
+link the foreign library. (Required by CMUCL)
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>success</returnvalue></term>
+ <listitem>
+ <para>A boolean flag, &t; if the library was able to be
+loaded successfully or if the library has been previously loaded,
+otherwise &nil;.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>Loads a foreign library. Applies a module name to functions
+within the library. Ensures that a library is only loaded once during
+a session.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <programlisting>
+ (load-foreign-library #p"/usr/lib/libmysqlclient.so"
+ :module "mysql"
+ :supporting-libraries '("c"))
+ => T
+ </programlisting>
+ </refsect1>
+ <refsect1>
+ <title>Side Effects</title>
+ <para>Loads the foreign code into the Lisp system.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Affected by</title>
+ <para>Ability to load the file.</para>
+ </refsect1>
+ <refsect1>
+ <title>Exceptional Situations</title>
+ <para>None.</para>
+ </refsect1>
+ </refentry>
+ </sect1>
</chapter>
projects / uffi.git / blobdiff