<refsect1>
<title>Examples</title>
<programlisting>
-(def-array ca :char)
+(def-array-pointer ca :unsigned-char)
(let ((fs (convert-to-foreign-string "ab")))
(values (null-char-p (deref-array fs 'ca 0))
(null-char-p (deref-array fs 'ca 2))))
</refentry>
- <refentry id="def-array">
+ <refentry id="def-array-pointer">
<refnamediv>
- <refname>def-array</refname>
- <refpurpose>Defines a foreign array type.
+ <refname>def-array-pointer</refname>
+ <refpurpose>Defines a pointer to a array of type.
</refpurpose>
<refclass>Macro</refclass>
</refnamediv>
<refsynopsisdiv>
<title>Syntax</title>
<synopsis>
- <function>def-array</function> <replaceable>name type</replaceable>
+ <function>def-array-pointer</function> <replaceable>name type</replaceable>
</synopsis>
</refsynopsisdiv>
<refsect1>
<refsect1>
<title>Description</title>
<para>
- Defines a foreign array type.
+ Defines a type tat is a pointer to an array of type.
</para>
</refsect1>
<refsect1>
<title>Examples</title>
<programlisting>
-(def-array byte-array :unsigned-char)
+(def-array-pointer byte-array-pointer :unsigned-char)
</programlisting>
</refsect1>
<refsect1>
<varlistentry>
<term><parameter>type</parameter></term>
<listitem>
- <para>A unevaluated type of foreign object to allocate.
+ <para>The type of foreign object to allocate. This parameter is evaluated.
</para>
</listitem>
</varlistentry>
<title>Examples</title>
<programlisting>
(def-struct ab (a :int) (b :double))
-(allocate-foreign-object ab)
+(allocate-foreign-object 'ab)
=> #<ptr>
</programlisting>
</refsect1>
</refentry>
+ <refentry id="with-foreign-object">
+ <refnamediv>
+ <refname>with-foreign-object</refname>
+ <refpurpose>Wraps the allocation of a foreign object around a body of code.
+ </refpurpose>
+ <refclass>Macro</refclass>
+ </refnamediv>
+ <refsynopsisdiv>
+ <title>Syntax</title>
+ <synopsis>
+ <function>with-foreign-object</function> <replaceable>(var type) &body body</replaceable> => <returnvalue>form-return</returnvalue>
+ </synopsis>
+ </refsynopsisdiv>
+ <refsect1>
+ <title>Arguments and Values</title>
+ <variablelist>
+ <varlistentry>
+ <term><parameter>var</parameter></term>
+ <listitem>
+ <para>The variable name to bind.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><parameter>type</parameter></term>
+ <listitem>
+ <para>The type of foreign object to allocate. This parameter is evaluated.
+ </para>
+ </listitem>
+ </varlistentry>
+ <varlistentry>
+ <term><returnvalue>form-return</returnvalue></term>
+ <listitem>
+ <para>The result of evaluating the <parameter>body</parameter>.
+ </para>
+ </listitem>
+ </varlistentry>
+ </variablelist>
+ </refsect1>
+ <refsect1>
+ <title>Description</title>
+ <para>
+This function wraps the allocation, binding, and destruction of a foreign object.
+On &cmucl; and
+&lw; platforms the object is stack allocated for efficiency. Benchmarks show that &acl; performs
+much better with static allocation.
+ </para>
+ </refsect1>
+ <refsect1>
+ <title>Examples</title>
+ <programlisting>
+(defun gethostname2 ()
+ "Returns the hostname"
+ (uffi:with-foreign-object (name '(:array :unsigned-char 256))
+ (if (zerop (c-gethostname (uffi:char-array-to-pointer name) 256))
+ (uffi:convert-from-foreign-string name)
+ (error "gethostname() failed."))))
+ </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>
+
<refentry id="pointer-address">
<refnamediv>
<refname>pointer-address</refname>
<refentry id="ensure-char-character">
<refnamediv>
<refname>ensure-char-character</refname>
- <refpurpose>Ensures that a dereferenced :char pointer is
+ <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
a character.
</refpurpose>
<refclass>Macro</refclass>
<refentry id="ensure-char-integer">
<refnamediv>
<refname>ensure-char-integer</refname>
- <refpurpose>Ensures that a dereferenced :char pointer is
+ <refpurpose>Ensures that a dereferenced <constant>:char</constant> pointer is
an integer.
</refpurpose>
<refclass>Macro</refclass>