</para>
</sect2>
- <sect2 id="uffi-declare">
- <title>uffi-declare</title>
+ <sect2 id="def-type">
+ <title>def-type</title>
<para>
- This is used wherever a <function>declare</function>
- expression can be placed. 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>
-(let ((my-structure (uffi:allocate-foreign-object 'a-struct)))
- (uffi:uffi-declare a-struct my-structure))
+(uffi:def-type my-struct-def my-struct-foreign-type)
</programlisting>
</para>
</sect2>
+ </sect1>
- <sect2 id="slot-type">
- <title>slot-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>
+ <sect1>
+ <title>Primitive Types</title>
+ <sect2>
+ <title>Overview</title>
<para>
- <programlisting>
-(eval
- `(defclass a-class ()
- ((char-ptr :type ,(uffi:slot-type (* :char))))))
- </programlisting>
+ 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>:char</constant> - Signed 8-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:unsigned-char</constant> - Unsigned 8-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:short</constant> - Signed 16-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:unsigned-short</constant> - Unsigned 16-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:int</constant> - Signed 32-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:unsigned-int</constant> - Unsigned 32-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:long</constant> - Signed 32-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:unsigned-long</constant> - Unsigned 32-bits</para>
+ </listitem>
+ <listitem>
+ <para><constant>:float</constant> - 32-bit floating point</para>
+ </listitem>
+ <listitem>
+ <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>
+ </listitem>
+ <listitem>
+ <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>
+ </listitem>
+ </itemizedlist>
</sect2>
- </sect1>
-
- <sect1>
- <title>Immediate Types</title>
<sect2>
<title>def-constant</title>
<para>
This is a thin wrapper around
- <function>defconstant</function>. It also exports the symbol
- from the package.
+ <function>defconstant</function>. It evaluates at
+ compile-time and exports the symbol from the package.
</para>
</sect2>
<sect2>
<para>
This is the main function for creating new types.
</para>
+ <sect3>
+ <title>Examples</title>
+ <para>
+ <programlisting>
+(def-type my-generic-pointer (* :void))
+(def-type a-double-float :double-float)
+(def-type char-ptr (* :char))
+ </programlisting>
+ </para>
+ </sect3>
</sect2>
<sect2>
<title>null-char-p</title>
<sect2>
<title>def-struct</title>
<para>
- Declares a structure.
+ Declares a structure. A special type is available as a slot in the field. It is
+ a pointer that points to an instance of the parent structure. It's type is
+ <constant>:pointer-self</constant>.
</para>
+ <sect3>
+ <title>Examples</title>
+ <para>
+ <programlisting>
+(def-struct foo (a :unsigned-int) (b :array 10) (next :pointer-self))
+ </programlisting>
+ </para>
+ </sect3>
</sect2>
<sect2 id="get-slot-value">
<title>get-slot-value</title>
<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>
- Allocates an instance of a foreign object.
+ Allocates an instance of a foreign object. It returns a pointer to the object.
</para>
</sect2>
<sect2>
</para>
</sect2>
<sect2>
- <title>+null-c-string-ptr+</title>
+ <title>+null-cstring-pointer+</title>
<para>
- A constant returning a &null; character pointer;
+ A constant &null; character pointer.
</para>
</sect2>
</sect1>
<sect1>
<title>Strings</title>
<sect2>
- <title>convert-from-c-string</title>
+ <title>Overview</title>
+ <para>
+ &uffi; has functions to two types of <varname>C</varname>-compatible
+ strings, <emphasis>cstring</emphasis> and <emphasis>foreign</emphasis> strings.
+cstrings are used as parameters to and from functions. An implementation, such as CMUCL,
+may not convert these to a foreign type for efficiency sake. Thus, it is not
+possible to "allocate" a cstring. In contrast, foreign strings
+always need to have memory for them.
+ </para>
+ </sect2>
+ <sect2>
+ <title>convert-from-cstring</title>
<para>
- Converts a Lisp string to a <varname>c-string</varname>.
+ Converts a Lisp string to a <varname>cstring</varname>.
</para>
</sect2>
<sect2>
- <title>convert-to-c-string</title>
+ <title>convert-to-cstring</title>
<para>
Converts a Lisp string to a
- <varname>c-string</varname>. These
- <varname>c-string's</varname> should be freed with
- <function>free-c-string</function>.
+ <varname>cstring</varname>. The
+ <varname>cstring</varname> should be freed with
+ <function>free-cstring</function>.
</para>
</sect2>
<sect2>
- <title>free-c-string</title>
+ <title>free-cstring</title>
<para>
Frees any memory possibly allocated by
- <function>convert-to-c-string</function>.
+ <function>convert-to-cstring</function>.
</para>
</sect2>
<sect2>
- <title>with-c-string</title>
+ <title>with-cstring</title>
<para>
- Binds a lexical variable to a newly allocated <varname>c-string</varname>. Automatically frees <varname>c-string</varname>.
+ 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>
<sect1>
- <title>Routine</title>
- <sect2>
- <title>def-routine</title>
- <para>
- This macro generates a &c; routine definition.
+ <title>Functions</title>
+ <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>
- </sect2>
+ </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.
+ <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>
- </sect2>
- </sect1>
-
+ </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