doc/ref_string.xml

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