doc/ref_string.xml

   1 <?xml version='1.0' ?>   <!-- -*- DocBook -*- -->
   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.xml">
   5 %myents;
   6 ]>
   7
   8 <reference id="strings">
   9       <title>Strings</title>
  10 <partintro>
  11 <title>Overview</title>
  12 <para>
  13
  14           &uffi; has functions to two types of
  15 <varname>C</varname>-compatible
  16           strings: <emphasis>cstring</emphasis> and
  17 <emphasis>foreign</emphasis> strings.
  18
  19 cstrings are used <emphasis>only</emphasis> as parameters to and from
  20 functions. In some implementations a cstring is not a foreign type but
  21 rather the Lisp string itself. On other platforms a cstring is a newly
  22 allocated foreign vector for storing characters. The following is an
  23 example of using cstrings to both send and return a value.
  24 </para>
  25
  26 <programlisting>
  27 (uffi:def-function ("getenv" c-getenv)
  28     ((name :cstring))
  29   :returning :cstring)
  30
  31 (defun my-getenv (key)
  32   "Returns an environment variable, or NIL if it does not exist"
  33   (check-type key string)
  34   (uffi:with-cstring (key-native key)
  35     (uffi:convert-from-cstring (c-getenv key-native))))
  36 </programlisting>
  37
  38 <para> In contrast, foreign strings are always a foreign vector of
  39 characters which have memory allocated. Thus, if you need to allocate
  40 memory to hold the return value of a string, you must use a foreign
  41 string and not a cstring.  The following is an example of using a foreign
  42 string for a return value.  </para>
  43
  44 <programlisting>
  45 (uffi:def-function ("gethostname" c-gethostname)
  46     ((name (* :unsigned-char))
  47      (len :int))
  48   :returning :int)
  49
  50 (defun gethostname ()
  51   "Returns the hostname"
  52   (let* ((name (uffi:allocate-foreign-string 256))
  53          (result-code (c-gethostname name 256))
  54          (hostname (when (zerop result-code)
  55                      (uffi:convert-from-foreign-string name))))
  56     (uffi:free-foreign-object name)
  57     (unless (zerop result-code)
  58       (error "gethostname() failed."))))
  59 </programlisting>
  60
  61 <para>  Foreign functions that return pointers to freshly allocated
  62 strings should in general not return cstrings, but foreign strings.
  63 (There is no portable way to release such cstrings from Lisp.)  The
  64 following is an example of handling such a function.  </para>
  65
  66 <programlisting>
  67 (uffi:def-function ("readline" c-readline)
  68     ((prompt :cstring))
  69   :returning (* :char))
  70
  71 (defun readline (prompt)
  72   "Reads a string from console with line-editing."
  73   (with-cstring (c-prompt prompt)
  74       (let* ((c-str (c-readline c-prompt))
  75              (str (convert-from-foreign-string c-str)))
  76         (uffi:free-foreign-object c-str)
  77         str)))
  78 </programlisting>
  79
  80 </partintro>
  81
  82     <refentry id="convert-from-cstring">
  83       <refnamediv>
  84         <refname>convert-from-cstring</refname>
  85         <refpurpose>Converts a cstring to a Lisp string.
  86         </refpurpose>
  87         <refclass>Macro</refclass>
  88       </refnamediv>
  89       <refsynopsisdiv>
  90         <title>Syntax</title>
  91         <synopsis>
  92           <function>convert-from-cstring</function> <replaceable>cstring</replaceable> => <returnvalue>string</returnvalue>
  93         </synopsis>
  94       </refsynopsisdiv>
  95       <refsect1>
  96         <title>Arguments and Values</title>
  97         <variablelist>
  98           <varlistentry>
  99             <term><parameter>cstring</parameter></term>
 100             <listitem>
 101               <para>A cstring.
 102               </para>
 103             </listitem>
 104           </varlistentry>
 105           <varlistentry>
 106             <term><returnvalue>string</returnvalue></term>
 107             <listitem>
 108               <para>A Lisp string.
 109               </para>
 110             </listitem>
 111           </varlistentry>
 112         </variablelist>
 113       </refsect1>
 114       <refsect1>
 115         <title>Description</title>
 116         <para>
 117           Converts a Lisp string to a <constant>cstring</constant>. This is
 118 most often used when processing the results of a foreign function
 119 that returns a cstring.
 120         </para>
 121       </refsect1>
 122       <refsect1>
 123         <title>Side Effects</title>
 124         <para>None.</para>
 125       </refsect1>
 126       <refsect1>
 127         <title>Affected by</title>
 128         <para>None.</para>
 129       </refsect1>
 130       <refsect1>
 131         <title>Exceptional Situations</title>
 132         <para>None.</para>
 133       </refsect1>
 134     </refentry>
 135
 136
 137     <refentry id="convert-to-cstring">
 138       <refnamediv>
 139         <refname>convert-to-cstring</refname>
 140         <refpurpose>Converts a Lisp string to a cstring.
 141         </refpurpose>
 142         <refclass>Macro</refclass>
 143       </refnamediv>
 144       <refsynopsisdiv>
 145         <title>Syntax</title>
 146         <synopsis>
 147           <function>convert-to-cstring</function> <replaceable>string</replaceable> => <returnvalue>cstring</returnvalue>
 148         </synopsis>
 149       </refsynopsisdiv>
 150       <refsect1>
 151         <title>Arguments and Values</title>
 152         <variablelist>
 153           <varlistentry>
 154             <term><parameter>string</parameter></term>
 155             <listitem>
 156               <para>A Lisp string.
 157               </para>
 158             </listitem>
 159           </varlistentry>
 160           <varlistentry>
 161             <term><returnvalue>cstring</returnvalue></term>
 162             <listitem>
 163               <para>A cstring.
 164               </para>
 165             </listitem>
 166           </varlistentry>
 167         </variablelist>
 168       </refsect1>
 169       <refsect1>
 170         <title>Description</title>
 171         <para>
 172           Converts a Lisp string to a
 173           <varname>cstring</varname>. The
 174           <varname>cstring</varname> should be freed with
 175           <function>free-cstring</function>.
 176         </para>
 177       </refsect1>
 178       <refsect1>
 179         <title>Side Effects</title>
 180         <para>On some implementations, this function allocates memory.</para>
 181       </refsect1>
 182       <refsect1>
 183         <title>Affected by</title>
 184         <para>None.</para>
 185       </refsect1>
 186       <refsect1>
 187         <title>Exceptional Situations</title>
 188         <para>None.</para>
 189       </refsect1>
 190     </refentry>
 191
 192
 193     <refentry id="free-cstring">
 194       <refnamediv>
 195         <refname>free-cstring</refname>
 196         <refpurpose>Free memory used by cstring.
 197         </refpurpose>
 198         <refclass>Macro</refclass>
 199       </refnamediv>
 200       <refsynopsisdiv>
 201         <title>Syntax</title>
 202         <synopsis>
 203           <function>free-cstring</function> <replaceable>cstring</replaceable>
 204         </synopsis>
 205       </refsynopsisdiv>
 206       <refsect1>
 207         <title>Arguments and Values</title>
 208         <variablelist>
 209           <varlistentry>
 210             <term><parameter>cstring</parameter></term>
 211             <listitem>
 212               <para>A cstring.
 213               </para>
 214             </listitem>
 215           </varlistentry>
 216         </variablelist>
 217       </refsect1>
 218       <refsect1>
 219         <title>Description</title>
 220         <para>
 221           Frees any memory possibly allocated by
 222           <function>convert-to-cstring</function>. On some implementions, a cstring is just the Lisp string itself.
 223         </para>
 224       </refsect1>
 225       <refsect1>
 226         <title>Side Effects</title>
 227         <para>None.</para>
 228       </refsect1>
 229       <refsect1>
 230         <title>Affected by</title>
 231         <para>None.</para>
 232       </refsect1>
 233       <refsect1>
 234         <title>Exceptional Situations</title>
 235         <para>None.</para>
 236       </refsect1>
 237     </refentry>
 238
 239
 240     <refentry id="with-cstring">
 241       <refnamediv>
 242         <refname>with-cstring</refname>
 243         <refpurpose>Binds a newly created cstring.
 244         </refpurpose>
 245         <refclass>Macro</refclass>
 246       </refnamediv>
 247       <refsynopsisdiv>
 248         <title>Syntax</title>
 249         <synopsis>
 250           <function>with-cstring</function> <replaceable>(cstring string) {body}</replaceable>
 251         </synopsis>
 252       </refsynopsisdiv>
 253       <refsect1>
 254         <title>Arguments and Values</title>
 255         <variablelist>
 256           <varlistentry>
 257             <term><parameter>cstring</parameter></term>
 258             <listitem>
 259               <para>A symbol naming the cstring to be created.
 260               </para>
 261             </listitem>
 262           </varlistentry>
 263           <varlistentry>
 264             <term><parameter>string</parameter></term>
 265             <listitem>
 266               <para>A Lisp string that will be translated to a cstring.
 267               </para>
 268             </listitem>
 269           </varlistentry>
 270           <varlistentry>
 271             <term><parameter>body</parameter></term>
 272             <listitem>
 273               <para>The body of where the cstring will be bound.
 274               </para>
 275             </listitem>
 276           </varlistentry>
 277         </variablelist>
 278       </refsect1>
 279       <refsect1>
 280         <title>Description</title>
 281         <para>
 282           Binds a symbol to a cstring created from conversion of a string. Automatically frees the <varname>cstring</varname>.
 283         </para>
 284       </refsect1>
 285       <refsect1>
 286         <title>Examples</title>
 287         <para>
 288             <programlisting>
 289 (def-function ("getenv" c-getenv)
 290    ((name :cstring))
 291    :returning :cstring)
 292
 293 (defun getenv (key)
 294   "Returns an environment variable, or NIL if it does not exist"
 295   (check-type key string)
 296   (with-cstring (key-cstring key)
 297     (convert-from-cstring (c-getenv key-cstring))))
 298             </programlisting>
 299           </para>
 300         </refsect1>
 301       <refsect1>
 302         <title>Side Effects</title>
 303         <para>None.</para>
 304       </refsect1>
 305       <refsect1>
 306         <title>Affected by</title>
 307         <para>None.</para>
 308       </refsect1>
 309       <refsect1>
 310         <title>Exceptional Situations</title>
 311         <para>None.</para>
 312       </refsect1>
 313     </refentry>
 314
 315
 316     <refentry id="convert-from-foreign-string">
 317       <refnamediv>
 318         <refname>convert-from-foreign-string</refname>
 319         <refpurpose>Converts a foreign string into a Lisp string.
 320         </refpurpose>
 321         <refclass>Macro</refclass>
 322       </refnamediv>
 323       <refsynopsisdiv>
 324         <title>Syntax</title>
 325         <synopsis>
 326           <function>convert-from-foreign-string</function> <replaceable>foreign-string &amp;key length null-terminated-p</replaceable> => <returnvalue>string</returnvalue>
 327         </synopsis>
 328       </refsynopsisdiv>
 329       <refsect1>
 330         <title>Arguments and Values</title>
 331         <variablelist>
 332           <varlistentry>
 333             <term><parameter>foreign-string</parameter></term>
 334             <listitem>
 335               <para>A foreign string.
 336               </para>
 337             </listitem>
 338           </varlistentry>
 339           <varlistentry>
 340             <term><parameter>length</parameter></term>
 341             <listitem>
 342               <para>The length of the foreign string to
 343 convert. The default is the length of the string until a &null;
 344 character is reached.
 345               </para>
 346             </listitem>
 347           </varlistentry>
 348           <varlistentry>
 349             <term><parameter>null-terminated-p</parameter></term>
 350             <listitem>
 351               <para>A boolean flag with a default value of &t; When true,
 352 the string is converted until the first &null; character is reached.
 353               </para>
 354             </listitem>
 355           </varlistentry>
 356           <varlistentry>
 357             <term><returnvalue>string</returnvalue></term>
 358             <listitem>
 359               <para>A Lisp string.
 360               </para>
 361             </listitem>
 362           </varlistentry>
 363         </variablelist>
 364       </refsect1>
 365       <refsect1>
 366         <title>Description</title>
 367         <para>
 368           Returns a Lisp string from a foreign string.
 369 Can translated ASCII and binary strings.
 370         </para>
 371       </refsect1>
 372       <refsect1>
 373         <title>Side Effects</title>
 374         <para>None.</para>
 375       </refsect1>
 376       <refsect1>
 377         <title>Affected by</title>
 378         <para>None.</para>
 379       </refsect1>
 380       <refsect1>
 381         <title>Exceptional Situations</title>
 382         <para>None.</para>
 383       </refsect1>
 384     </refentry>
 385
 386
 387     <refentry id="convert-to-foreign-string">
 388       <refnamediv>
 389         <refname>convert-to-foreign-string</refname>
 390         <refpurpose>Converts a Lisp string to a foreign string.
 391         </refpurpose>
 392         <refclass>Macro</refclass>
 393       </refnamediv>
 394       <refsynopsisdiv>
 395         <title>Syntax</title>
 396         <synopsis>
 397           <function>convert-to-foreign-string</function> <replaceable>string</replaceable> => <returnvalue>foreign-string</returnvalue>
 398         </synopsis>
 399       </refsynopsisdiv>
 400       <refsect1>
 401         <title>Arguments and Values</title>
 402         <variablelist>
 403           <varlistentry>
 404             <term><parameter>string</parameter></term>
 405             <listitem>
 406               <para>A Lisp string.
 407               </para>
 408             </listitem>
 409           </varlistentry>
 410           <varlistentry>
 411             <term><returnvalue>foreign-string</returnvalue></term>
 412             <listitem>
 413               <para>A foreign string.
 414               </para>
 415             </listitem>
 416           </varlistentry>
 417         </variablelist>
 418       </refsect1>
 419       <refsect1>
 420         <title>Description</title>
 421         <para>
 422           Converts a Lisp string to a foreign string. Memory should be
 423           freed with <function>free-foreign-object</function>.
 424         </para>
 425       </refsect1>
 426       <refsect1>
 427         <title>Side Effects</title>
 428         <para>None.</para>
 429       </refsect1>
 430       <refsect1>
 431         <title>Affected by</title>
 432         <para>None.</para>
 433       </refsect1>
 434       <refsect1>
 435         <title>Exceptional Situations</title>
 436         <para>None.</para>
 437       </refsect1>
 438     </refentry>
 439
 440
 441
 442     <refentry id="allocate-foreign-string">
 443       <refnamediv>
 444         <refname>allocate-foreign-string</refname>
 445         <refpurpose>Allocates space for a foreign string.
 446         </refpurpose>
 447         <refclass>Macro</refclass>
 448       </refnamediv>
 449       <refsynopsisdiv>
 450         <title>Syntax</title>
 451         <synopsis>
 452           <function>allocate-foreign-string</function> <replaceable>size &amp;key unsigned</replaceable> => <returnvalue>foreign-string</returnvalue>
 453         </synopsis>
 454       </refsynopsisdiv>
 455       <refsect1>
 456         <title>Arguments and Values</title>
 457         <variablelist>
 458           <varlistentry>
 459             <term><parameter>size</parameter></term>
 460             <listitem>
 461               <para>The size of the space to be allocated in bytes.
 462               </para>
 463             </listitem>
 464           </varlistentry>
 465           <varlistentry>
 466             <term><parameter>unsigned</parameter></term>
 467             <listitem>
 468               <para>A boolean flag with a default value of &t;. When true,
 469 marks the pointer as an <constant>:unsigned-char</constant>.
 470               </para>
 471             </listitem>
 472           </varlistentry>
 473           <varlistentry>
 474             <term><returnvalue>foreign-string</returnvalue></term>
 475             <listitem>
 476               <para>A foreign string which has undefined contents.
 477               </para>
 478             </listitem>
 479           </varlistentry>
 480         </variablelist>
 481       </refsect1>
 482       <refsect1>
 483         <title>Description</title>
 484         <para>
 485           Allocates space for a foreign string. Memory should
 486           be freed with <function>free-foreign-object</function>.
 487         </para>
 488       </refsect1>
 489       <refsect1>
 490         <title>Side Effects</title>
 491         <para>None.</para>
 492       </refsect1>
 493       <refsect1>
 494         <title>Affected by</title>
 495         <para>None.</para>
 496       </refsect1>
 497       <refsect1>
 498         <title>Exceptional Situations</title>
 499         <para>None.</para>
 500       </refsect1>
 501     </refentry>
 502
 503   </reference>