<sect1>
<title>Immediate Types</title>
+ <sect2>
+ <title>Overview</title>
+ <para>
+ Immediate 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>
+ <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>:single-float</constant> - 32-bit floating point</para>
+ </listitem>
+ <listitem>
+ <para><constant>:double-float</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>
+ - An 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>
<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>
<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-cstring-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>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>
</sect1>
<sect1>
- <title>Routine</title>
+ <title>Functions</title>
<sect2>
<title>def-function</title>
<para>
- This macro generates a &c; routine definition.
+ This macro generates a &c; function definition.
</para>
</sect2>
</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 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.
+ </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" "mysql" '("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