« back to all changes in this revision
Viewing changes to doc/impext.xml
- browse files at revision 6
- compare with another revision
- download diff
- download tarball
- view history from revision 6
- Committer: Bazaar Package Importer
- Author(s): Peter Van Eynde
- Date: 2009-09-03 04:52:49 UTC
- mfrom: (1.1.10 upstream)
- Revision ID: james.westby@ubuntu.com-20090903045249-2qevpq13p4pc0sgi
Tags: 1:2.48-1
* New upstream release
* move clisp-link patch into git repository
* Moved instructionset definition patch into git.
* removed quilt horror
* Updated Standards-Version no real changes
* Changed Section to lisp
* go to debhelper v7
* added build conflict against libsigsegv 2.7 and higher
* updated doc directory that gets build by upstream
* added ${misc:Depends} to Depends
* updated copyright file
* Changed makemake to not use identical temporary targets a few times,
(Closes: #494413)
* Make clisp-link always work with bash. Closes: #530054
* Fix bashism in clisp.sh Closes: #530055
* Added debian/README.building file
* added conflict with older clc
* move clisp-link patch into git repository
* Moved instructionset definition patch into git.
* removed quilt horror
* Updated Standards-Version no real changes
* Changed Section to lisp
* go to debhelper v7
* added build conflict against libsigsegv 2.7 and higher
* updated doc directory that gets build by upstream
* added ${misc:Depends} to Depends
* updated copyright file
* Changed makemake to not use identical temporary targets a few times,
(Closes: #494413)
* Make clisp-link always work with bash. Closes: #530054
* Fix bashism in clisp.sh Closes: #530055
* Added debian/README.building file
* added conflict with older clc
- files added:
- debian/README.building
- modules/dbus
- files removed:
- clisp.lsm
- debian/patches
- files modified:
- COPYRIGHT
added
removed
doc/impext.xml
50
50
51
51
<section id="init-hooks"><title>Customizing Initialization</title>
52
52
<para>&init-hooks; is run like this:<programlisting language="lisp">
53
(&mapc; #'&funcall; &init-hooks;)
53
(&ignore-errors; (&mapc; #'&funcall; &init-hooks;))
54
54
</programlisting></para>
55
55
<section id="init-hooks-function"><title>The difference between
56
56
&init-hooks; and &init-function;</title>
84
84
<varlistentry><term><constant>:QUIET</constant></term>
85
85
<listitem><simpara>If this argument is not &nil;, the startup banner
86
86
and the good-bye message will be suppressed, as if by &opt-q;.</simpara>
87
<simpara>This is ¬-e; recommended for interactive application
88
delivery, please <emphasis>append</emphasis> your banner to ours
89
(using &init-function;) instead of <emphasis>replacing</emphasis> it.
87
<simpara>This is ¬-e; recommended for interactive application delivery,
88
please <emphasis>append</emphasis> your banner to ours (using
89
&init-function;) instead of <emphasis>replacing</emphasis> it.
90
90
</simpara></listitem></varlistentry>
91
91
<varlistentry><term><constant>:VERBOSE</constant></term>
92
92
<listitem><simpara>Print a message after writing the file.
100
100
<listitem><simpara>This argument specifies a function that will be
101
101
executed at startup of the saved image, before entering the standard &repl;
102
102
(but after all other initialization, see <xref linkend="cradle-grave"/>);
103
thus, if you want to avoid the &repl;, you have to call
104
<link linkend="quit"><function>EXT:EXIT</function></link> at the end
105
of the init function yourself
103
thus, if you want to avoid the &repl;, you have to call &exit; at the
104
end of the init function yourself
106
105
(this does not prevent &fini-hooks; from being run).</simpara>
107
106
<simpara>See <olink targetdoc="man" targetptr="opt-exec-file">the
108
107
manual</olink> for passing command line arguments to this function.
109
</simpara><simpara>See also &init-hooks; and &fini-hooks;.</simpara>
108
</simpara><simpara>See also &init-hooks; and &fini-hooks;.</simpara>
110
109
</listitem></varlistentry>
111
110
<varlistentry><term><constant>:SCRIPT</constant></term>
112
111
<listitem><para>This options determines the handling of positional
143
142
<screen>&sh-prompt; clisp -i myfile -x '(&savemem;)'</screen>
144
143
will produce an image without any global handlers inherited
145
144
from the batch mode of the above command.</para></listitem></varlistentry>
146
<varlistentry><term><constant>:EXECUTABLE</constant></term>
147
<listitem><simpara>When non-&nil;, the saved file will be an
145
<varlistentry id="image-exec"><term><constant>:EXECUTABLE</constant></term>
146
<listitem><simpara>When non-&nil;, the saved file will be a
148
147
standalone executable.
149
148
In this case, the &mem-file; extension is not added.
150
149
On &win32; and &cygwin; the extension <filename>#P".exe"</filename>
151
is added instead.</simpara></listitem></varlistentry>
152
</variablelist>
150
is added instead.</simpara>
151
<para>Additionally, if this argument is &zero;, the standard
152
&clisp; command line options will ¬-e; be processed by the
153
executable but will be placed into &args; instead.
154
This is convenient for application delivery, so that your
155
&clisp;-based application can accept, e.g., &opt-x;.
156
To override this feature of the image, you have to prefix the
157
options with <literal>"--clisp"</literal>, e.g.,
158
use <option>--clisp-x</option> instead of &opt-x;.
159
This, given such a &clisp;-based application, you can get to an
160
ordinary &clisp; &repl; by doing <screen>
161
&sh-prompt; application --clisp-x '(&savemem; "myclisp" :executable t :init-function nil)'
162
&sh-prompt; ./myclisp
163
[1]> (<link linkend="factorial">!</link> 20)
164
2432902008176640000</screen>
165
These instructions are also printed by
166
<option>--clisp--help</option>.</para>
167
<simpara>Of course, this feature opens a <emphasis>security hole</emphasis>
168
if the application is running <function role="unix">setuid</function> root,
169
therefore &clisp; resets the effective group and user IDs to the real
170
ones if it sees a <literal>"--clisp-*"</literal> option.
171
</simpara></listitem></varlistentry></variablelist>
153
172
You can use this memory image with the &opt-M; option.
154
173
On &unix; systems, you may compress it with &gnu; &gzip; to save disk
155
174
space.</para>
156
175
157
<warning id="image-portability"><title>Image Portability</title>
176
<section id="image-portability"><title>Image Portability</title>
158
177
<para>Memory images are ¬-e; portable across different platforms
159
178
(in contrast with platform-independent &fasl-file; files).
160
179
They are ¬-e; even portable across &linkset;s: image saved using
161
the &full; &linkset; cannot be used with the &base; runtime:<screen>
180
the &full; &linkset; cannot be used with the &base; &rt;:<screen>
162
181
&sh-prompt; clisp -K full -x '(&savemem;)'
163
182
&sh-prompt; clisp -K base -M lispinit.mem
164
base/lisp.run: initialization file `lispinit.mem' was not created by this version of CLISP runtime
165
</screen></para></warning>
183
base/lisp.run: initialization file `lispinit.mem' was not created by this version of CLISP runtime</screen>
184
See also <ulink role="sfmail" url="BF6EFF38DF3FA647BBD932720D8BED650BAA11%40parmbx02.ilog.biz"/>/<ulink role="gmane" url="devel/17757"/>.</para></section>
166
185
167
186
</section>
168
187
169
188
<section id="quit"><title>Quitting &clisp;</title>
170
189
171
190
<para>The functions <simplelist>
172
<member><code>(<function>EXT:EXIT</function>
173
&optional-amp; &status-r;)</code></member>
174
<member><code>(<function>EXT:QUIT</function>
175
&optional-amp; &status-r;)</code></member>
176
<member><code>(<function>EXT:BYE</function>
177
&optional-amp; &status-r;)</code></member></simplelist>
191
<member><code>(&exit; &optional-amp; &status-r;)</code></member>
192
<member><code>(EXT:QUIT &optional-amp; &status-r;)</code></member>
193
<member><code>(EXT:BYE &optional-amp; &status-r;)</code></member></simplelist>
178
194
- all synonymous - terminate &clisp;. If &status-r; is non-&nil;,
179
195
&clisp; aborts with the supplied numeric error &status-r;, i.e.,
180
196
the OS environment is informed that the &clisp; session did not
187
203
188
204
<section id="i18n"><title>Internationalization of &clisp;</title>
189
205
190
<variablelist><varlistentry><term>Internationalization
191
(<quote>i18n</quote>)</term>
206
<variablelist><title>Glossary</title>
207
<varlistentry><term>Internationalization (<quote>i18n</quote>)</term>
192
208
<listitem><simpara>preparing a program so that it can use multiple
193
209
national languages and national cultural conventions without requiring
194
210
further source code changes.</simpara></listitem></varlistentry>
195
<varlistentry><term>Localization (<quote>l10n</quote>)</term>
196
<listitem><simpara>providing the data - mostly textual translations -
197
necessary for an internationalized program to work in a particular
198
language and with particular cultural conventions.
211
<varlistentry><term>Localization (<quote>l10n</quote>)</term>
212
<listitem><simpara>providing the data - mostly textual translations -
213
necessary for an internationalized program to work in a particular
214
language and with particular cultural conventions.
199
215
</simpara></listitem></varlistentry></variablelist>
200
216
201
217
<para>&clisp; is internationalized, and is localized for the languages
203
219
&clisp; also supports internationalized Lisp programs, through
204
220
&ggettext;, see <xref linkend="i18n-mod"/>.</para>
205
221
206
<para>User programs can also be internationalized,
207
see <xref linkend="i18n-mod"/>.</para>
208
209
222
<section id="language"><title>The Language</title>
210
223
211
224
<warning><para>The facilities described in this section will
226
239
227
240
<para>This is controlled by the &symbol-macro;
228
241
<firstterm>&curr-lang;<indexterm id="curr-lang" significance="preferred">
229
<primary id="curr-lang-i"><varname>*CURRENT-LANGUAGE*</varname>
242
<primary><varname>*CURRENT-LANGUAGE*</varname>
230
243
</primary></indexterm></firstterm>,
231
which can be set at run time as well as using the &opt-L; start-up option.
244
which can be set at run time as well as using the &opt-L; command line option.
232
245
If you wish to change the
233
246
<olink targetdoc="man" targetptr="opt-locale">locale directory</olink>
234
247
at run time too, you can do that by setting &curr-lang; to a &cons-t;
237
250
238
251
<para>More languages can be defined through the macro
239
252
<firstterm>&deflang;<indexterm id="deflang" significance="preferred">
240
<primary id="deflang-i"><function>DEFLANGUAGE</function>
241
</primary></indexterm></firstterm>:
253
<primary><function>DEFLANGUAGE</function></primary></indexterm></firstterm>:
242
254
<code>(&deflang; &lang-r;)</code>.
243
255
For such an additional language to take effect, you must install the
244
256
corresponding message catalog, or translate the messages yourself,
245
using &ggettext; and &emacs; (or &xemacs;) po-mode.</para>
257
using &ggettext; and &emacs; (or &xemacs;)
258
<ulink url="google">po-mode</ulink>.</para>
246
259
247
260
<para>This works only for strings. For arbitrary language-dependent
248
261
Lisp objects, you define one through the macro
249
262
<firstterm>&def-i-l;<indexterm id="def-i-l" significance="preferred">
250
<primary id="def-i-l-i"><function>DEFINTERNATIONAL</function>
263
<primary><function>DEFINTERNATIONAL</function>
251
264
</primary></indexterm></firstterm>:
252
265
<code>(&def-i-l; &symbol-r; &optional-amp;
253
266
(<replaceable>default-language</replaceable> &t;))</code> and add
254
267
language-dependent values through the macro
255
268
<firstterm>&defloc;<indexterm id="defloc" significance="preferred">
256
<primary id="defloc-i"><function>DEFLOCALIZED</function>
257
</primary></indexterm></firstterm>:
269
<primary><function>DEFLOCALIZED</function></primary></indexterm></firstterm>:
258
270
<code>(&defloc; &symbol-r; &lang-r;
259
271
<replaceable>value-form</replaceable>)</code>
260
272
(One such form for each language. Languages without an assigned
261
273
value will be treated like the default-language.)
262
274
You can then access the localized value by calling
263
275
<firstterm>&localized;<indexterm id="localized" significance="preferred">
264
<primary id="localized-i"><function>LOCALIZED</function>
265
</primary></indexterm></firstterm>:
276
<primary><function>LOCALIZED</function></primary></indexterm></firstterm>:
266
277
<code>(&localized; &symbol-r; &optional-amp; &lang-r;)</code></para>
267
278
268
279
</section>
312
323
<computeroutput>&t;</computeroutput>
313
324
</programlisting></para>
314
325
326
<formalpara id="enc1-1"><title><quote>1:1</quote> encodings</title>
327
<para>Encodings which define a bijection between character and byte
328
sequences are called &enc1-1;s. &iso-8859-1; is an example of such an
329
encoding: any byte sequence corresponds to some character sequence and
330
vice versa. &ascii;, however, is ¬-e; a &enc1-1;: there are no
331
characters for bytes in the range [128;255]. &utf-8; is ¬-e; a
332
&enc1-1; either: some byte sequences do not correspond to any character
333
sequence.</para></formalpara>
334
315
335
</section>
316
336
317
337
<section id="charset"><title>Character Sets</title>
409
429
<listitem id="charset-ISO-8859-7"><simpara><constant>ISO-8859-7</constant>,
410
430
&ascii-iso-ext; Greek language.</simpara></listitem>
411
431
<listitem id="charset-ISO-8859-8"><simpara><constant>ISO-8859-8</constant>,
412
&ascii-iso-ext; Hebrew language (without punctuation).
413
</simpara></listitem>
432
&ascii-iso-ext; Hebrew language (without punctuation).</simpara></listitem>
414
433
<listitem id="charset-ISO-8859-9"><simpara><constant>ISO-8859-9</constant>,
415
434
&ascii-iso-ext; Turkish language.</simpara></listitem>
416
435
<listitem id="charset-ISO-8859-10"><simpara><constant>ISO-8859-10</constant>,
448
467
<listitem id="charset-MAC-CYRILLIC"><simpara><constant>MAC-CYRILLIC</constant>,
449
468
&ascii-pl-ext;.</simpara></listitem>
450
469
<listitem id="charset-MAC-DINGBAT"><simpara><constant>MAC-DINGBAT</constant>,
451
a platform specific character set.
452
</simpara></listitem>
470
a platform specific character set.</simpara></listitem>
453
471
<listitem id="charset-MAC-GREEK"><simpara><constant>MAC-GREEK</constant>,
454
472
&ascii-pl-ext;.</simpara></listitem>
455
473
<listitem id="charset-MAC-HEBREW"><simpara><constant>MAC-HEBREW</constant>,
472
490
<listitem id="charset-CP437"><simpara><constant>CP437</constant>, a DOS oldie,
473
491
&ascii-pl-ext;.</simpara></listitem>
474
492
<listitem id="charset-CP437-IBM"><simpara><constant>CP437-IBM</constant>,
475
an IBM variant of <constant>CP437</constant>.
476
</simpara></listitem>
493
an IBM variant of <constant>CP437</constant>.</simpara></listitem>
477
494
<listitem id="charset-CP737"><simpara><constant>CP737</constant>, a DOS oldie,
478
&ascii-pl-ext;, meant to be suitable for the Greek language.
479
</simpara></listitem>
495
&ascii-pl-ext;, &good-for; the Greek language.</simpara></listitem>
480
496
<listitem id="charset-CP775"><simpara><constant>CP775</constant>, a DOS oldie,
481
&ascii-pl-ext;, meant to be suitable for some Baltic languages.
482
</simpara></listitem>
497
&ascii-pl-ext;, &good-for; some Baltic languages.</simpara></listitem>
483
498
<listitem id="charset-CP850"><simpara><constant>CP850</constant>, a DOS oldie,
484
499
&ascii-pl-ext;.</simpara></listitem>
485
500
<listitem id="charset-CP852"><simpara><constant>CP852</constant>, a DOS oldie,
487
502
<listitem id="charset-CP852-IBM"><simpara><constant>CP852-IBM</constant>,
488
503
an IBM variant of <constant>CP852</constant>.</simpara></listitem>
489
504
<listitem id="charset-CP855"><simpara><constant>CP855</constant>, a DOS oldie,
490
&ascii-pl-ext;, meant to be suitable for the Russian language.
491
</simpara></listitem>
505
&ascii-pl-ext;, &good-for; the Russian language.</simpara></listitem>
492
506
<listitem id="charset-CP857"><simpara><constant>CP857</constant>, a DOS oldie,
493
&ascii-pl-ext;, meant to be suitable for the Turkish language.
494
</simpara></listitem>
507
&ascii-pl-ext;, &good-for; the Turkish language.</simpara></listitem>
495
508
<listitem id="charset-CP860"><simpara><constant>CP860</constant>, a DOS oldie,
496
&ascii-pl-ext;, meant to be suitable for the Portuguese language.
497
</simpara></listitem>
509
&ascii-pl-ext;, &good-for; the Portuguese language.</simpara></listitem>
498
510
<listitem id="charset-CP860-IBM"><simpara><constant>CP860-IBM</constant>,
499
an IBM variant of <constant>CP860</constant>.
500
</simpara></listitem>
511
an IBM variant of <constant>CP860</constant>.</simpara></listitem>
501
512
<listitem id="charset-CP861"><simpara><constant>CP861</constant>, a DOS oldie,
502
&ascii-pl-ext;, meant to be suitable for the Icelandic language.
503
</simpara></listitem>
513
&ascii-pl-ext;, &good-for; the Icelandic language.</simpara></listitem>
504
514
<listitem id="charset-CP861-IBM"><simpara><constant>CP861-IBM</constant>,
505
an IBM variant of <constant>CP861</constant>.
506
</simpara></listitem>
515
an IBM variant of <constant>CP861</constant>.</simpara></listitem>
507
516
<listitem id="charset-CP862"><simpara><constant>CP862</constant>, a DOS oldie,
508
&ascii-pl-ext;, meant to be suitable for the Hebrew language.
509
</simpara></listitem>
517
&ascii-pl-ext;, &good-for; the Hebrew language.</simpara></listitem>
510
518
<listitem id="charset-CP862-IBM"><simpara><constant>CP862-IBM</constant>,
511
an IBM variant of <constant>CP862</constant>.
512
</simpara></listitem>
519
an IBM variant of <constant>CP862</constant>.</simpara></listitem>
513
520
<listitem id="charset-CP863"><simpara><constant>CP863</constant>, a DOS oldie,
514
521
&ascii-pl-ext;.</simpara></listitem>
515
522
<listitem id="charset-CP863-IBM"><simpara><constant>CP863-IBM</constant>,
516
an IBM variant of <constant>CP863</constant>.
517
</simpara></listitem>
523
an IBM variant of <constant>CP863</constant>.</simpara></listitem>
518
524
<listitem id="charset-CP864"><simpara><constant>CP864</constant>, a DOS oldie,
519
meant to be suitable for the Arabic language.
520
</simpara></listitem>
525
&good-for; the Arabic language.</simpara></listitem>
521
526
<listitem id="charset-CP864-IBM"><simpara><constant>CP864-IBM</constant>,
522
527
an IBM variant of <constant>CP864</constant>.
523
528
</simpara></listitem>
524
529
<listitem id="charset-CP865"><simpara><constant>CP865</constant>, a DOS oldie,
525
&ascii-pl-ext;, meant to be suitable for some Nordic languages.
526
</simpara></listitem>
530
&ascii-pl-ext;, &good-for; some Nordic languages.</simpara></listitem>
527
531
<listitem id="charset-CP865-IBM"><simpara><constant>CP865-IBM</constant>,
528
532
an IBM variant of <constant>CP865</constant>.
529
533
</simpara></listitem>
530
534
<listitem id="charset-CP866"><simpara><constant>CP866</constant>, a DOS oldie,
531
&ascii-pl-ext;, meant to be suitable for the Russian language.
532
</simpara></listitem>
535
&ascii-pl-ext;, &good-for; the Russian language.</simpara></listitem>
533
536
<listitem id="charset-CP869"><simpara><constant>CP869</constant>, a DOS oldie,
534
&ascii-pl-ext;, meant to be suitable for the Greek language.
535
</simpara></listitem>
537
&ascii-pl-ext;, &good-for; the Greek language.</simpara></listitem>
536
538
<listitem id="charset-CP869-IBM"><simpara><constant>CP869-IBM</constant>,
537
539
an IBM variant of <constant>CP869</constant>.
538
540
</simpara></listitem>
539
541
<listitem id="charset-CP874"><simpara><constant>CP874</constant>, a DOS oldie,
540
&ascii-pl-ext;, meant to be suitable for the Thai language.
541
</simpara></listitem>
542
&ascii-pl-ext;, &good-for; the Thai language.</simpara></listitem>
542
543
<listitem id="charset-CP874-IBM"><simpara><constant>CP874-IBM</constant>,
543
544
an IBM variant of <constant>CP874</constant>.
544
545
</simpara></listitem>
549
550
<listitem id="charset-WINDOWS-1251"><simpara><constant>WINDOWS-1251</constant>
550
551
≡ <constant>CP1251</constant>,
551
552
&ascii-pl-ext;, heavily incompatible with ISO-8859-5,
552
meant to be suitable for the Russian language.
553
</simpara></listitem>
553
&good-for; the Russian language.</simpara></listitem>
554
554
<listitem id="charset-WINDOWS-1252"><simpara><constant>WINDOWS-1252</constant>
555
555
≡ <constant>CP1252</constant>,
556
556
a platform specific extension of the ISO-8859-1 character set.
558
558
<listitem id="charset-WINDOWS-1253"><simpara><constant>WINDOWS-1253</constant>
559
559
≡ <constant>CP1253</constant>,
560
560
&ascii-pl-ext;, gratuitously incompatible with ISO-8859-7,
561
meant to be suitable for the Greek language.
562
</simpara></listitem>
561
&good-for; the Greek language.</simpara></listitem>
563
562
<listitem id="charset-WINDOWS-1254"><simpara><constant>WINDOWS-1254</constant>
564
563
≡ <constant>CP1254</constant>,
565
564
a platform specific extension of the ISO-8859-9 character set.
573
572
<!-- #endif /* GNU_LIBICONV */ -->
574
573
<listitem id="charset-WINDOWS-1256"><simpara><constant>WINDOWS-1256</constant>
575
574
≡ <constant>CP1256</constant>,
576
&ascii-pl-ext;, meant to be suitable for the Arabic language.
577
</simpara></listitem>
575
&ascii-pl-ext;, &good-for; the Arabic language.</simpara></listitem>
578
576
<listitem id="charset-WINDOWS-1257"><simpara><constant>WINDOWS-1257</constant>
579
577
≡ <constant>CP1257</constant>,
580
578
&ascii-pl-ext;.</simpara></listitem>
581
579
<!-- #ifdef GNU_LIBICONV -->
582
580
<listitem id="charset-WINDOWS-1258"><simpara><constant>WINDOWS-1258</constant>
583
≡ <constant>CP1258</constant>,
584
&ascii-pl-ext;, meant to be suitable for the Vietnamese language.
585
&charset-glibc-libiconv;</simpara></listitem>
581
≡ <constant>CP1258</constant>, &ascii-pl-ext;, &good-for; the
582
Vietnamese language. &charset-glibc-libiconv;</simpara></listitem>
586
583
<!-- #endif /* GNU_LIBICONV */ -->
587
584
<listitem id="charset-HP-ROMAN8"><simpara><constant>HP-ROMAN8</constant>,
588
585
&ascii-pl-ext;.</simpara></listitem>
709
706
that the other &iconv; implementations are broken in various ways and
710
707
we do not want to deal with random &clisp; crashes caused by those bugs.
711
708
If your system supplies an &iconv; implementation which passes the
712
&libiconv;'s test suite, please report that to &clisp-list; and a
709
&libiconv;'s test suite, please report that
710
to <ulink url="ml">clisp-list</ulink> and a
713
711
future &clisp; version will use &iconv; on your system.</simpara>
714
712
715
713
</listitem></varlistentry></variablelist>
803
801
<variablelist>
804
802
<varlistentry><term><firstterm>&path-enc;
805
803
<indexterm id="path-enc" significance="preferred">
806
<primary id="path-enc-i"><varname>*PATHNAME-ENCODING*</varname>
804
<primary><varname>*PATHNAME-ENCODING*</varname>
807
805
</primary></indexterm></firstterm></term>
808
<listitem><simpara>is the encoding used for pathnames in the file
809
system. Normally, this should be a 1:1 encoding.
810
Its &line-term; mode is ignored.</simpara></listitem></varlistentry>
806
<listitem><para>is the encoding used for converting filenames in the
807
file system (represented with byte sequences by the OS) to lisp
808
&pathname-t; components (&string-t;s).
809
If this encoding is incompatible with some file names on your system,
810
file system access (e.g., &directory;) may &signal; &error-t;s,
811
thus extreme caution is recommended if this is ¬-e; a &enc1-1;.
812
Sometimes it may not be obvious that the encoding is involved at all.
813
E.g., on &win32;: <programlisting language="lisp">
814
(&parse-namestring; (&string; #\ARMENIAN_SMALL_LETTER_RA))
815
*** - PARSE-NAMESTRING: syntax error in filename "ռ" at position 0
816
</programlisting>when &path-enc; is &utf-16; because then
817
<literal role="data">#\ARMENIAN_SMALL_LETTER_RA</literal> corresponds
818
to the 4 bytes <literal role="data">#(255 254 124 5)</literal>
819
and the byte <literal role="data">124</literal> is ¬-e; a valid
820
byte for a &win32; file name because it
821
means <literal role="data">|</literal> in &ascii;.</para>
822
<simpara>The set of valid pathname <emphasis>bytes</emphasis> is
823
determined by the &autoconf; test
824
<filename role="clisp-cvs">src/m4/filecharset.m4</filename>
825
at configure time. While rather stable for the first 127 bytes,
826
on &win32; it varies wildly for the bytes 128-256, depending on the
827
OS version and the file system.</simpara>
828
<simpara>The &line-term; mode of &path-enc; is ignored.</simpara>
829
</listitem></varlistentry>
811
830
<varlistentry><term><firstterm>&term-enc;
812
831
<indexterm id="term-enc" significance="preferred">
813
<primary id="term-enc-i"><varname>*TERMINAL-ENCODING*</varname>
832
<primary><varname>*TERMINAL-ENCODING*</varname>
814
833
</primary></indexterm></firstterm></term>
815
834
<listitem><simpara>is the encoding used for communication with the
816
835
terminal, in particular by &terminal-io-var;.
817
836
</simpara></listitem></varlistentry>
818
837
<varlistentry><term><firstterm>&misc-enc;
819
838
<indexterm id="misc-enc" significance="preferred">
820
<primary id="misc-enc-i"><varname>*MISC-ENCODING*</varname>
839
<primary><varname>*MISC-ENCODING*</varname>
821
840
</primary></indexterm></firstterm></term>
822
841
<listitem><simpara>is the encoding used for access to &env-var;s,
823
842
command line options, and the like. Its &line-term; mode is ignored.
825
844
<!-- #if defined(DYNAMIC_FFI) -->
826
845
<varlistentry><term><firstterm>&foreign-enc;
827
846
<indexterm id="foreign-enc" significance="preferred">
828
<primary id="foreign-enc-i"><varname>*FOREIGN-ENCODING*</varname>
847
<primary><varname>*FOREIGN-ENCODING*</varname>
829
848
</primary></indexterm></firstterm></term>
830
849
<listitem><simpara>is the encoding for strings passed through the
831
&ffi-pac; (some platforms only). If it is a 1:1 encoding,
850
&ffi-pac; (some platforms only). If it is a &enc1-1;,
832
851
i.e. an encoding in which every character is represented by one byte,
833
852
it is also used for passing characters through the &ffi-pac;.
834
853
</simpara></listitem></varlistentry>
937
956
938
957
<para>In order to specify the behavior of a generic stream, the user
939
958
must define &clos; methods on the following &clos; generic
940
functions. The function
941
<function>gstream:generic-stream-<replaceable>xyz</replaceable></function>
942
corresponds to the &cl; function
943
<function><replaceable>xyz</replaceable></function>. They all take a
944
controller and some number of arguments.</para>
959
functions. The function <function>gstream:generic-stream-&x-r;</function>
960
corresponds to the &cl; function <function>&x-r;</function>.
961
They all take a controller and some number of arguments.</para>
945
962
946
963
<variablelist>
947
<varlistentry><term><code>(<function>gstream:generic-stream-read-char</function>
964
<varlistentry><term><code>(gstream:generic-stream-read-char
948
965
<replaceable>controller</replaceable>)</code></term>
949
966
<listitem><simpara> Returns and consumes the next character, &nil; at
950
967
end of file. Takes one argument, the controller object.
951
968
</simpara></listitem></varlistentry>
952
<varlistentry><term><code>(<function>gstream:generic-stream-peek-char</function>
969
<varlistentry><term><code>(gstream:generic-stream-peek-char
953
970
<replaceable>controller</replaceable>)</code></term>
954
971
<listitem><simpara> Returns the next character, &nil; at end of file. A
955
972
second value indicates whether the side effects associated with
957
974
&read-char; was done, &nil; means that no side effects were done.
958
975
Takes one argument, the controller object.
959
976
</simpara></listitem></varlistentry>
960
<varlistentry><term><code>(<function>gstream:generic-stream-read-byte</function>
977
<varlistentry><term><code>(gstream:generic-stream-read-byte
961
978
<replaceable>controller</replaceable>)</code></term>
962
979
<listitem><simpara>Returns and consumes the next integer, &nil; at end
963
980
of file. Takes one argument, the controller object.
964
981
</simpara></listitem></varlistentry>
965
<varlistentry><term><code>(<function>gstream:generic-stream-read-char-will-hang-p</function>
982
<varlistentry><term><code>(gstream:generic-stream-read-char-will-hang-p
966
983
<replaceable>controller</replaceable>)</code></term>
967
984
<listitem><simpara>This generic function is used to query the stream's
968
985
input status. It returns &nil; if
970
987
<function>gstream:generic-stream-peek-char</function> will certainly
971
988
return immediately. Otherwise it returns true.
972
989
</simpara></listitem></varlistentry>
973
<varlistentry><term><code>(<function>gstream:generic-stream-write-char</function>
990
<varlistentry><term><code>(gstream:generic-stream-write-char
974
991
<replaceable>controller</replaceable> &ch-r;)</code></term>
975
992
<listitem><simpara>The first argument is the controller object.
976
993
The second argument is the character to be written.
977
994
</simpara></listitem></varlistentry>
978
<varlistentry><term><code>(<function>gstream:generic-stream-write-byte</function>
995
<varlistentry><term><code>(gstream:generic-stream-write-byte
979
996
<replaceable>controller</replaceable>
980
997
<replaceable>by</replaceable>)</code></term>
981
998
<listitem><simpara>The first argument is the controller object.
982
999
The second argument is the integer to be written.
983
1000
</simpara></listitem></varlistentry>
984
<varlistentry><term><code>(<function>gstream:generic-stream-write-string</function>
1001
<varlistentry><term><code>(gstream:generic-stream-write-string
985
1002
<replaceable>controller</replaceable>
986
1003
&string-r; &start-r; &len-r;)</code></term>
987
1004
<listitem><simpara>Writes the subsequence of &string-r; starting from
988
1005
&start-r; of length &len-r;.
989
1006
The first argument is the controller object.
990
1007
</simpara></listitem></varlistentry>
991
<varlistentry><term><code>(<function>gstream:generic-stream-clear-input</function>
1008
<varlistentry><term><code>(gstream:generic-stream-clear-input
992
1009
<replaceable>controller</replaceable>)</code></term>
993
<term><code>(<function>gstream:generic-stream-clear-output</function>
994
<replaceable>controller</replaceable>)</code></term>
995
<term><code>(<function>gstream:generic-stream-finish-output</function>
996
<replaceable>controller</replaceable>)</code></term>
997
<term><code>(<function>gstream:generic-stream-force-output</function>
998
<replaceable>controller</replaceable>)</code></term>
999
<term><code>(<function>gstream:generic-stream-close</function>
1010
<term><code>(gstream:generic-stream-clear-output
1011
<replaceable>controller</replaceable>)</code></term>
1012
<term><code>(gstream:generic-stream-finish-output
1013
<replaceable>controller</replaceable>)</code></term>
1014
<term><code>(gstream:generic-stream-force-output
1015
<replaceable>controller</replaceable>)</code></term>
1016
<term><code>(gstream:generic-stream-close
1000
1017
<replaceable>controller</replaceable>)</code></term>
1001
1018
<listitem><simpara>Take one argument, the controller object.
1002
1019
</simpara></listitem></varlistentry>
1559
1576
<section id="ansi"><title>Maximum ANSI CL compliance</title>
1560
1577
1561
1578
<para>Some &ansi-cl; features are turned off by default for convenience and
1562
for backwards compatibility.
1579
backward compatibility.
1563
1580
They can be switched on, all at once, by setting the &symbol-macro;
1564
1581
&ansi; to &t;, or they can be switched on individually.
1565
1582
Setting &ansi; to &t; implies the following:</para>
1577
1594
<listitem><simpara>Setting &loop-ansi; to &t;.</simpara></listitem>
1578
1595
<listitem><simpara>Setting &pr-empty-arr-ansi; to &t;.</simpara></listitem>
1579
1596
<listitem><simpara>Setting &pr-unreadable-ansi; to &t;.</simpara></listitem>
1580
<listitem><simpara>Setting &defun-accept-spelalist; to &nil;</simpara></listitem>
1597
<listitem><simpara>Setting &defun-accept-spelalist; to &nil;.</simpara></listitem>
1581
1598
</orderedlist>
1582
1599
1583
1600
<note><para>If you run &clisp; with the &opt-ansi; switch or set
1602
1619
<listitem><simpara>Setting &loop-ansi; to &nil;.</simpara></listitem>
1603
1620
<listitem><simpara>Setting &pr-empty-arr-ansi; to &nil;.</simpara></listitem>
1604
1621
<listitem><simpara>Setting &pr-unreadable-ansi; to &nil;.</simpara></listitem>
1605
<listitem><simpara>Setting &defun-accept-spelalist; to &t;</simpara></listitem>
1622
<listitem><simpara>Setting &defun-accept-spelalist; to &t;.</simpara></listitem>
1606
1623
</orderedlist>
1607
1624
1608
1625
</section>
1643
1660
memoizes the &pri-val; of &form-r; from its first evaluation.
1644
1661
</para></section>
1645
1662
1646
<section id="with-collect">
1647
<title>Macro <function>EXT:WITH-COLLECT</function></title>
1663
<section id="with-collect"><title>Macro &with-collect;</title>
1648
1664
<para>Similar to the &loop;'s
1649
<ulink url="&clhs;/Body/sec_6-1-3.html"><constant>collect</constant></ulink>
1665
<ulink role="clhs" url="sec_6-1-3"><literal>COLLECT</literal></ulink>
1650
1666
construct, except that it is looks more "Lispy" and can appear
1651
1667
arbitrarily deep. It defines local macros (with ¯olet;) which
1652
1668
collect objects given to it into lists, which are then returned as
1655
1671
(dotimes (i 10) (if (oddp i) (c0 i) (c1 i))))
1656
1672
<computeroutput>(1 3 5 7 9)</computeroutput> ;
1657
1673
<computeroutput>(0 2 4 6 8)</computeroutput>
1658
</programlisting> returns two &list-t;s <returnvalue>(1 3 5 7 9)</returnvalue>
1659
and <returnvalue>(0 2 4 6 8)</returnvalue> as &mul-val;.
1660
</para></section>
1674
</programlisting> returns two &list-t;s as &mul-val;.</para></section>
1675
1676
<section id="compile-time-value">
1677
<title>Macro <function>EXT:COMPILE-TIME-VALUE</function></title>
1678
<para>Sometimes one may want to call an expensive function at
1679
compilation time and write the &pri-val; into the &fasl-file; file,
1680
thus speeding up loading the &fasl-file; file.
1681
E.g., let your file <filename>primes.lisp</filename> be
1682
<programlisting language="lisp">
1683
(defun primes-list (limit)
1684
"Return the list of all primes smaller than LIMIT."
1685
...)
1686
(defvar *all-primes* (compile-time-value (primes-list &most-positive-fixnum;)))
1687
</programlisting>
1688
Then <variablelist>
1689
<varlistentry><term><code>(&load; "primes.lisp")</code></term>
1690
<listitem><simpara>will ¬-e; call <function>primes-list</function>
1691
and <varname>*all-primes*</varname> will be &nil;.
1692
</simpara></listitem></varlistentry>
1693
<varlistentry><term><code>(&compile-file; "primes.lisp")</code></term>
1694
<listitem><simpara>will call <function>primes-list</function> (and
1695
will probably take a long time) and will write the resulting list
1696
into <code>(&compile-file-pathname; "primes.lisp")</code>
1697
</simpara></listitem></varlistentry>
1698
<varlistentry><term><code>(&load; (&compile-file-pathname;
1699
"primes.lisp"))</code></term>
1700
<listitem><simpara>will ¬-e; call <function>primes-list</function>
1701
but <varname>*all-primes*</varname> will be the list computed during
1702
compilation.</simpara></listitem></varlistentry></variablelist></para>
1703
<para>An alternative is to save a &mem-image;, which is faster than &fasl-file;
1704
file but <link linkend="image-portability">less portable</link>.</para>
1705
</section>
1661
1706
1662
1707
<section id="with-gensyms">
1663
<title>Macro <function>EXT:WITH-GENSYMS</function></title>
1708
<title>Macro <function>EXT:WITH-GENSYMS</function></title>
1664
1709
<para>Similar to its namesake from
1665
1710
<ulink url="http://www.paulgraham.com/">Paul Graham</ulink>'s book
1666
1711
<ulink url="http://www.paulgraham.com/onlisp.html"><quote>On
1708
1753
<para>Defined in
1709
1754
<link linkend="clhs-lisp"><filename>clhs.lisp</filename></link>,
1710
1755
they allow downloading data over the Internet using the &http; protocol.
1711
<code>(&open-http; url &key-amp; &if-does-not-exist;)</code> opens
1756
<code>(&open-http; url &key-amp; &if-does-not-exist; :LOG)</code> opens
1712
1757
a &sock; connection to the <replaceable>url</replaceable> host,
1713
1758
sends the <command>GET</command> request,
1714
1759
and returns two values: the &socket-stream; and content length.
1717
1762
<code>(EXT:WITH-HTTP-INPUT ((&var-r; &cont-r;) url) &body-amp; body)</code>
1718
1763
additionally binds &cont-r; to the content length.</para>
1719
1764
<para>&open-http; will check &http-proxy; on startup and parse the &env-var;
1720
<envar>HTTP_PROXY</envar> if &http-proxy; is &nil;.</para></section>
1765
<envar>HTTP_PROXY</envar> if &http-proxy; is &nil;.</para>
1766
<para>The <constant>:LOG</constant> argument binds &http-log-stream;.</para>
1767
</section>
1768
1769
<section id="http-log-stream"><title>Variable &http-log-stream;</title>
1770
<para>Function &open-http; logs its actions to &http-log-stream;
1771
which is initially set to &terminal-io-var;.</para></section>
1721
1772
1722
1773
<section id="browse-url"><title>Function &browse-url;</title>
1723
1774
<para>Function <code>(&browse-url; url &key-amp; &browser-k; &out-k;)</code>
1735
1786
If no <literal role="data">#\@</literal> is present,
1736
1787
&name-r; and &pass-r; are &nil;.
1737
1788
If no <literal role="data">#\:</literal> is present,
1738
&pass-r; (or &port-r;) are &nil;.</para>
1789
&pass-r; (or &port-r;) is &nil;.</para>
1739
1790
<para>Use function <code>(EXT:HTTP-PROXY &optional-amp; (&string-t;
1740
(&getenv; "http_proxy")))</code> to reset &http-proxy;.</para></section>
1791
(&getenv; "http_proxy")))</code> to reset
1792
&http-proxy;.</para></section>
1793
1794
<section id="canonicalize"><title>Function &canonicalize;</title>
1795
<para>If you want to canonicalize a &value-r; before further processing it, you
1796
can pass it to &canonicalize; together with a &sequence-t; of &function-t;s:
1797
<code>(&canonicalize; &value-r; <replaceable>functions</replaceable>
1798
&key-amp; (test '&eql;) (max-iter 1024))</code> will call &func-r;s on
1799
&value-r; until it stabilizes under <replaceable>test</replaceable>
1800
(which should be a valid &hash-table-test;) and return the stabilized
1801
value and the number of iterations the stabilization required.</para>
1802
<para>E.g., &new-clx; uses it together with
1803
<firstterm><varname>XLIB:*CANONICALIZE-ENCODING*</varname></firstterm>
1804
to fix the broken encoding names returned by the &X; (e.g., convert
1805
<literal>"iso8859-1"</literal> to <literal>"ISO-8859-1"</literal>)
1806
before passing them over to &make-encoding;. If you encounter an &encoding;
1807
&error-t; in &new-clx;, you can augment this variable to avoid it.
1808
</para></section>
1809
1741
1810
</section>
1742
1811
1743
1812
<section id="customize"><title>Customizing &clisp; behavior</title>
1776
1845
<member>&flocont;</member>
1777
1846
<member>&floratcont;</member>
1778
1847
<member>&foreign-enc;</member>
1848
<member>&http-log-stream;</member>
1779
1849
<member>&http-proxy;</member>
1780
1850
<member>&impnotes-root;</member>
1781
1851
<member>&impnotes-root-default;</member>
1786
1856
<member><link linkend="inspect"><varname>CUSTOM:*INSPECT-PRINT-LENGTH*</varname></link></member>
1787
1857
<member><link linkend="inspect"><varname>CUSTOM:*INSPECT-PRINT-LEVEL*</varname></link></member>
1788
1858
<member><link linkend="inspect"><varname>CUSTOM:*INSPECT-PRINT-LINES*</varname></link></member>
1789
<member><olink targetdoc="man" targetptr="opt-libdir"
1790
><varname>CUSTOM:*LIB-DIRECTORY*</varname></olink></member>
1859
<member>&libdir;</member>
1791
1860
<member>&load-comp;</member>
1792
1861
<member>&load-echo;</member>
1793
1862
<member>&load-lpt-db;</member>
1816
1885
<member>&prompt-finish;</member>
1817
1886
<member>&prompt-start;</member>
1818
1887
<member>&prompt-step;</member>
1888
<member>&reopen;</member>
1819
1889
<member>&err-pr-bt;</member>
1820
1890
<member>&savemem-verbose;</member>
1821
1891
<member>&count-ansi;</member>
1822
1892
<member>&source-types;</member>
1823
1893
<member>&suppress-check-redef;</member>
1894
<member>&suppress-similar-const-redef;</member>
1824
1895
<member>&sys-pack-list;</member>
1825
1896
<member>&term-enc;</member>
1826
1897
<member>&trace-indent;</member>
1853
1924
(macrolet ((baz (x) `(bar ,x)))
1854
1925
(symbol-macrolet ((z 3))
1855
1926
(baz z)))))
1856
<computeroutput>(locally (print 3))</computeroutput> ; the expansion
1857
<computeroutput>&t;</computeroutput> ; indicator: some expansion has actually been done
1927
<computeroutput>(locally (print 3))</computeroutput> <lineannotation>the expansion</lineannotation>
1928
<computeroutput>&t;</computeroutput> <lineannotation>indicator: some expansion has actually been done</lineannotation>
1858
1929
</programlisting></para>
1859
1930
1860
1931
<para>This is sometimes called a <quote>code walker</quote>,
1895
1966
&body-r;)</code></term>
1896
1967
<listitem><simpara>binds
1897
1968
<firstterm>&scr-win;<indexterm id="scr-win" significance="preferred">
1898
<primary id="scr-win-i"><varname>*WINDOW*</varname>
1969
<primary><varname>*WINDOW*</varname>
1899
1970
</primary></indexterm></firstterm>
1900
1971
to a <type>WINDOW-STREAM</type> and executes &body-r;.
1901
1972
The stream is guaranteed to be closed when the body is left.
1969
2040
extension <filename>exe</filename>.</para>
1970
2041
<para>For historical reasons, all examples appear to assume &unix; and
1971
2042
use the <filename>run</filename> file type (<quote>extension</quote>)
1972
for the &clisp; run-time.
2043
for the &clisp; &rt;.
1973
2044
This does ¬-e; mean that they will not work on &win32;.</para>
1974
2045
</note>
1975
2046
1976
2047
<section id="mod-overview"><title>Overview</title>
1977
2048
1978
<para>&clisp; has a facility for adding external modules (written in
1979
&c-lang;, for example). It is invoked through &clisp-link;.</para>
2049
<para><emphasis>External modules</emphasis> are a mechanism to add
2050
extensions (written in &c-lang;, for example) to &clisp;.
2051
Extending &clisp; using an external module requires creating a &modset;
2052
and adding it to an existing &linkset; using &clisp-link; to prodice a
2053
new &linkset; which contains the extension. </para>
1980
2054
2055
<simplesect id="modset"><title>Module Set</title>
1981
2056
<para>A <firstterm>module<indexterm id="module" significance="preferred">
1982
<primary id="module-i">module</primary></indexterm></firstterm> is a
1983
piece of external code which defines extra Lisp objects, symbols and
1984
functions. A module <firstterm>name</firstterm> must consist of the
1985
characters <filename>A</filename>-<filename>Z</filename>,
2057
<primary>module</primary></indexterm></firstterm> is a piece of code
2058
(&c-lang; or Lisp) which defines extra (non-core) Lisp objects, symbols
2059
and functions. Together with &link-sh;, which describes how to add the
2060
module to an existing &clisp;, it comprises a &modset;.</para>
2061
<para>More formally,
2062
<firstterm>&modset;<indexterm id="modseti" significance="preferred">
2063
<primary>module set</primary></indexterm></firstterm>
2064
is a directory containing:
2065
<variablelist><varlistentry><term>&link-sh;</term>
2066
<listitem><simpara>some &sh; commands, which prepare the directory
2067
for linking, and set some &env-var;s, see <xref linkend="mod-vars"/>
2068
</simpara></listitem></varlistentry>
2069
<varlistentry><term>all other files that define the module functionality</term>
2070
<listitem><simpara>needed by &link-sh;</simpara></listitem></varlistentry>
2071
</variablelist></para>
2072
<para>In &link-sh; the &modset; directory is referred to
2073
as <varname>$modulename/</varname>.</para>
2074
<para>A module <firstterm>name<indexterm id="module-name">
2075
<primary>module</primary><secondary>name</secondary></indexterm></firstterm>
2076
must consist of the characters <filename>A</filename>-<filename>Z</filename>,
1986
2077
<filename>a</filename>-<filename>z</filename>, <filename>_</filename>,
1987
<filename>0</filename>-<filename>9</filename>.
1988
The module name <quote>clisp</quote> is reserved.
1989
Normally a module name is derived from the corresponding file name.</para>
1990
1991
<para>&clisp-link; needs a directory containing:
1992
<itemizedlist>
1993
<listitem><simpara><filename>"modules.c"</filename></simpara></listitem>
1994
<listitem><simpara>&clisp-h;</simpara></listitem>
1995
</itemizedlist>
1996
&clisp-link; expects to find these files in a
1997
subdirectory <filename>linkkit/</filename> of the current directory.
1998
This can be overridden by the &env-var; <envar>CLISP_LINKKIT</envar>.</para>
1999
2000
<para>&clisp-link; operates on &clisp; &linkset;s and on &modset;s.</para>
2001
2002
<simplesect id="linkset"><title>&linkset;</title>
2003
<para>A <firstterm>&linkset;<indexterm id="linkseti" significance="preferred">
2004
<primary id="linkset-i">linking set</primary></indexterm></firstterm>
2005
is a directory containing:
2006
<variablelist>
2007
<varlistentry><term><filename>makevars</filename></term>
2008
<listitem><para>some &sh; commands, setting the variables
2009
<variablelist>&varlist-table;<varlistentry><term><envar>CC</envar></term>
2010
<listitem><simpara>the &c-lang; compiler
2011
</simpara></listitem></varlistentry>
2012
<varlistentry><term><envar>CPPFLAGS</envar></term>
2013
<listitem><simpara>flags for the &c-lang; compiler, when preprocessing
2014
or compiling</simpara></listitem></varlistentry>
2015
<varlistentry><term><envar>CFLAGS</envar></term>
2016
<listitem><simpara>flags for the &c-lang; compiler, when compiling or
2017
linking</simpara></listitem></varlistentry>
2018
<varlistentry><term><envar>CLFLAGS</envar></term>
2019
<listitem><simpara>flags for the &c-lang; compiler, when linking
2020
</simpara></listitem></varlistentry>
2021
<varlistentry><term><envar>LIBS</envar></term>
2022
<listitem><simpara>libraries to use when linking (either present in
2023
the &linkset; directory, or system-wide)
2024
</simpara></listitem></varlistentry>
2025
<varlistentry><term><envar>X_LIBS</envar></term>
2026
<listitem><simpara>additional &X; libraries to use
2027
</simpara></listitem></varlistentry>
2028
<varlistentry><term><envar>RANLIB</envar></term>
2029
<listitem><simpara>the ranlib command
2030
</simpara></listitem></varlistentry>
2031
<varlistentry><term><envar>FILES</envar></term>
2032
<listitem><simpara>the list of files needed when linking
2033
</simpara></listitem></varlistentry>
2034
</variablelist></para></listitem></varlistentry>
2078
<filename>0</filename>-<filename>9</filename>.</para>
2079
<para>The module name <quote>clisp</quote> is reserved.</para>
2080
</simplesect>
2081
2082
<simplesect id="linkset"><title>Linking Set</title>
2083
<para>A <firstterm>&linkset;<indexterm id="linkseti" significance="preferred">
2084
<primary>linking set</primary></indexterm></firstterm>
2085
is a collection of files (&rt;, &mem-image; &c) which allows
2086
performing two major tasks:
2087
<orderedlist><listitem><para>Running &clisp;: to run a &clisp;
2088
contained in some &linkset; &dir-r;, call<screen>
2089
&sh-prompt; &dir-r;/lisp.run &opt-M; &dir-r;/lispinit.mem</screen>
2090
or <screen>&sh-prompt; clisp &opt-K; &dir-r;</screen>
2091
(recommended, since it also passes
2092
<option><olink targetdoc="man" targetptr="opt-libdir">-B</olink></option>
2093
to the &rt;).</para></listitem>
2094
<listitem><simpara>Adding a &modset; to create a new &linkset; which
2095
will contain the module functionality.</simpara></listitem></orderedlist>
2096
The &clisp; build directory contains three &linkset;s in
2097
directories <command>boot</command>, &base;, and &full;, and a &clisp;
2098
installation normally contains two &linkset;s: &base;, and &full;</para>
2099
<para>More formally, a &linkset; is a directory containing at least
2100
these files:<variablelist>
2101
<varlistentry><term>&lisp-run;</term>
2102
<listitem><simpara>the executable &rt;</simpara></listitem></varlistentry>
2103
<varlistentry><term>&lispinit;</term>
2104
<listitem><simpara>the &mem-image;</simpara></listitem></varlistentry>
2035
2105
<varlistentry><term><filename>modules.h</filename></term>
2036
2106
<listitem><simpara>the list of modules contained in this &linkset;
2037
2107
</simpara></listitem></varlistentry>
2038
2108
<varlistentry><term><filename>modules.o</filename></term>
2039
2109
<listitem><simpara>the compiled list of modules contained in this &linkset;
2040
2110
</simpara></listitem></varlistentry>
2041
<varlistentry><term>all the <filename>FILES</filename></term>
2111
<varlistentry><term><filename>makevars</filename></term>
2112
<listitem><para>some &sh; commands, setting the variables
2113
<variablelist>&varlist-table;<varlistentry><term><envar>CC</envar></term>
2114
<listitem><simpara>the &c-lang; compiler
2115
</simpara></listitem></varlistentry>
2116
<varlistentry><term><envar>CPPFLAGS</envar></term>
2117
<listitem><simpara>flags for the &c-lang; compiler, when preprocessing
2118
or compiling</simpara></listitem></varlistentry>
2119
<varlistentry><term><envar>CFLAGS</envar></term>
2120
<listitem><simpara>flags for the &c-lang; compiler, when compiling or
2121
linking</simpara></listitem></varlistentry>
2122
<varlistentry><term><envar>CLFLAGS</envar></term>
2123
<listitem><simpara>flags for the &c-lang; compiler, when linking
2124
</simpara></listitem></varlistentry>
2125
<varlistentry><term><envar>LIBS</envar></term>
2126
<listitem><simpara>libraries to use when linking (either present in
2127
the &linkset; directory, or system-wide)
2128
</simpara></listitem></varlistentry>
2129
<varlistentry><term><envar>X_LIBS</envar></term>
2130
<listitem><simpara>additional &X; libraries to use
2131
</simpara></listitem></varlistentry>
2132
<varlistentry><term><envar>RANLIB</envar></term>
2133
<listitem><simpara>the ranlib command
2134
</simpara></listitem></varlistentry>
2135
<varlistentry><term><envar>FILES</envar></term>
2136
<listitem><simpara>the list of files needed when linking
2137
</simpara></listitem></varlistentry>
2138
</variablelist></para></listitem></varlistentry>
2139
<varlistentry><term>all the <envar>FILES</envar></term>
2042
2140
<listitem><simpara>listed in <filename>makevars</filename>
2043
2141
</simpara></listitem></varlistentry>
2044
<varlistentry><term>&lisp-run;</term>
2045
<listitem><simpara>the executable</simpara></listitem></varlistentry>
2046
<varlistentry><term>&lispinit;</term>
2047
<listitem><simpara>the &mem-image;</simpara></listitem></varlistentry>
2048
</variablelist></para>
2049
2050
<para>To run a &clisp; contained in some &linkset; &directory-r;, call<screen>
2051
&sh-prompt; &directory-r;/lisp.run &opt-M; &directory-r;/lispinit.mem</screen>
2052
or <screen>&sh-prompt; clisp &opt-K; &directory-r;</screen>
2053
(recommended, since it also passes
2054
<option><olink targetdoc="man" targetptr="opt-libdir">-B</olink></option>
2055
to the run-time).</para></simplesect>
2056
2057
<simplesect id="modset"><title>&modset;</title>
2058
<para>A <firstterm>&modset;<indexterm id="modseti" significance="preferred">
2059
<primary id="modset-i">module set</primary></indexterm></firstterm>
2060
is a directory containing:
2061
<variablelist>
2062
<varlistentry><term>&link-sh;</term>
2063
<listitem><simpara>some &sh; commands, which prepare the directory
2064
before linking, and set the variables <envar>NEW_FILES</envar>,
2065
<envar>NEW_LIBS</envar>, <envar>NEW_MODULES</envar>, &mod-load;
2066
and optionally &mod-preload;</simpara></listitem></varlistentry>
2067
<varlistentry><term>and any other files</term>
2068
<listitem><simpara>needed by &link-sh;
2069
</simpara></listitem></varlistentry>
2070
</variablelist></para>
2071
2072
<para>In &link-sh; the &modset; directory is referred to
2073
as <varname>$modulename/</varname>.</para></simplesect>
2142
</variablelist></para>
2143
</simplesect>
2144
2145
<simplesect id="clisp-link"><title>Operating on &modset;s and &linkset;s</title>
2146
2147
<para>Adding one or several &modset;s to a &linkset;s produces a new
2148
&linkset; which contains the functionality of those modules in addition
2149
to all the functionality present in the original &linkset;.
2150
This is done by the &clisp-link; shell script, installed in &libdir;,
2151
so that you can invoke it with
2152
<screen>&sh-prompt; `&clisp-cmd; &opt-b;`/&clisp-link;</screen></para>
2153
2154
<variablelist><title>&clisp-link; commands</title>
2155
<varlistentry><term>create</term>
2156
<listitem><para>The command
2157
<screen>&sh-prompt; &clisp-link; create &mod-r; &file-r; ...</screen>
2158
creates a &modset; in &mod-r; directory which refers
2159
(via symbolic links) to files &file-r;...
2160
The files are expected to be modules of their own.
2161
</para></listitem></varlistentry>
2162
<varlistentry><term>add</term>
2163
<listitem><para>The command
2164
<screen>&sh-prompt; &clisp-link; add &source-r; &dest-r; &mod-r; ...</screen>
2165
combines the &linkset; in directory &source-r; and the &module;s in
2166
directories &mod-r;... to a new &linkset;, in the directory &dest-r;
2167
which is newly created.</para></listitem></varlistentry>
2168
<varlistentry><term>run</term>
2169
<listitem><para>The command
2170
<screen>&sh-prompt; &clisp-link; run &source-r; &mod-r; ...</screen>
2171
runs the &linkset; in directory &source-r;, with the &module;s
2172
in directories &mod-r;...
2173
If &clisp; has been built with the configuration option &with-dynmod;,
2174
the loading will be performed <link linkend="mod-dynload">dynamically</link>.
2175
Otherwise - this is much slower - a temporary &linkset; will be created
2176
and deleted afterwards.</para></listitem></varlistentry></variablelist>
2177
2178
<formalpara id="clisp-link-kit"><title>Requirements</title>
2179
<para>&clisp-link; needs a <quote>link kit</quote> directory containing:
2180
<itemizedlist>
2181
<listitem><simpara><filename>"modules.c"</filename></simpara></listitem>
2182
<listitem><simpara>&clisp-h;</simpara></listitem>
2183
</itemizedlist> &clisp-link; expects to find these files in a
2184
subdirectory <filename>linkkit/</filename> of the current directory.
2185
or in its own installation directory (i.e., &libdir;).
2186
This can be overridden by the &env-var; <envar>CLISP_LINKKIT</envar>.
2187
</para></formalpara>
2188
2189
<para>See also <xref linkend="mod-set-example"/>.</para>
2190
</simplesect>
2074
2191
2075
2192
<simplesect id="mod-vars"><title>Module set variables</title>
2076
2193
<para>The following variables should be defined in &link-sh;.</para>
2077
2194
<variablelist>
2078
2195
<varlistentry><term><envar>NEW_FILES</envar></term>
2079
<listitem><simpara>the space-separated list of files that
2080
belong to the &modset; and will belong to every new &linkset;.
2081
</simpara></listitem></varlistentry>
2196
<listitem><simpara>the space-separated list of object files that
2197
belong to the &modset; and will belong to every new &linkset; linked
2198
with this &modset;.</simpara></listitem></varlistentry>
2082
2199
<varlistentry><term><envar>NEW_LIBS</envar></term>
2083
<listitem><simpara>the space-separated list of files or
2200
<listitem><simpara>the space-separated list of object files, libraries or
2084
2201
&c-lang; compiler switches that need to be passed to the &c-lang;
2085
2202
compiler when linking the &lisp-run; belonging to a new &linkset;.
2086
2203
</simpara></listitem></varlistentry>
2087
2204
<varlistentry><term><envar>NEW_MODULES</envar></term>
2088
2205
<listitem><simpara>the space-separated list of the module names
2089
2206
belonging to the &modset;. Normally, every &c-file; file in the
2090
&modset; defines a module of its own. The module name is derived
2091
from the file name.</simpara></listitem></varlistentry>
2207
&modset; defines a module of its own. The module name is usually
2208
derived from the file name.</simpara></listitem></varlistentry>
2092
2209
<varlistentry id="mod-load"><term>&mod-load;</term>
2093
2210
<listitem><simpara>the space-separated list of Lisp files to load
2094
2211
before building the &lispinit; belonging to a new &linkset;.
2113
2230
</simpara></warning></listitem></varlistentry>
2114
2231
</variablelist></simplesect>
2115
2232
2116
<simplesect id="mod-create"><title>Creating &linkset;s</title>
2117
<para>The command <screen>
2118
&sh-prompt; &clisp-link; create-module-set &mod-r; <replaceable>file1.c</replaceable> ...
2119
</screen> creates a &modset; in &mod-r; directory which refers
2120
(via symbolic links) to <replaceable>file1.c</replaceable> etc.
2121
The files are expected to be modules of their own.</para>
2122
2123
<para>The command <screen>
2124
&sh-prompt; &clisp-link; add-module-set &mod-r; &source-r; &dest-r;
2125
</screen> combines a &linkset; in directory &source-r; and a
2126
&module; in directory &mod-r; to a new &linkset;, in the directory
2127
&dest-r; which is newly created.</para>
2128
2129
<para>The command <screen>
2130
&sh-prompt; &clisp-link; run &source-r; &mod-r; ...
2131
</screen> runs the &linkset; in directory &source-r;, with the &module;
2132
in directory &mod-r; loaded. More than one module can be specified.
2133
If &clisp; has been built with the configuration option &with-dynmod;,
2134
the loading will be performed <link linkend="mod-dynload">dynamically</link>.
2135
Otherwise - this is much slower - a temporary &linkset; will be created
2136
and deleted afterwards.</para>
2137
</simplesect>
2138
2139
2233
</section>
2140
2234
2141
2235
<section id="modinit"><title>Module initialization</title>
2220
2314
flag &with-dynmod;.</emphasis></subtitle>
2221
2315
2222
2316
<note><para>Dynamic loading does not work on all operating systems
2223
(<function role="unix">dlopen</function> or equivalent is required).
2224
</para></note>
2317
(&dlopen; or equivalent is required).</para></note>
2225
2318
<note><para>&with-dynmod; precludes some optimizations which
2226
2319
are enabled by default.</para></note>
2227
2320
2239
2332
This serves to register external functions which operate on Lisp-level
2240
2333
structures with &clisp;.</para>
2241
2334
2242
<para>To use <function role="unix">dlopen</function> with modules,
2243
you should add <option>-fPIC</option> to the module's compilation options.
2244
Something like <command>cc -shared -o &name-r;.so &name-r;.o</command>
2335
<para>To use &dlopen; with modules, you should add
2336
<option>-fPIC</option> to the module's compilation options. Something like
2337
<screen>&sh-prompt; cc -shared -o &name-r;.so &name-r;.o</screen>
2245
2338
may be needed to produce the shared object file.</para>
2246
2339
2247
2340
</section>
2248
2341
2249
2342
<section id="mod-set-example"><title>Example</title>
2250
2343
<example id="mod-set-ex-bindings">
2344
<title>Create a &modset; with &glibc; bindings</title>
2251
2345
<para>To link in the &ffi-pac; bindings for the &gnu;/&linux; operating
2252
2346
system, the following steps are needed. (Step 1 and step 2 need not be
2253
2347
executed in this order.)</para>
2254
2348
2255
2349
<procedure><step><title>Create a new &modset;</title>
2256
<screen>&sh-prompt; &clisp-link; create-module-set linux /<replaceable>somewhere</replaceable>/bindings/linux.c</screen></step>
2350
<screen>&sh-prompt; &clisp-link; create linux /&path-r;/bindings/linux.c</screen></step>
2257
2351
2258
2352
<step><title>Modify the newly created
2259
2353
<filename>linux/&link-sh;</filename></title>
2262
2356
with <screen>NEW_LIBS="$file_list -lm"</screen></para></step>
2263
2357
<step><title>load <filename>linux.fas</filename> before saving the
2264
2358
&mem-image;</title><para>replace <screen>TO_LOAD=''</screen> with
2265
<screen>TO_LOAD='/<replaceable>somewhere</replaceable>/bindings/linux.fas'</screen></para></step></substeps></step>
2359
<screen>TO_LOAD='/&path-r;/bindings/linux.fas'</screen></para></step>
2360
</substeps></step>
2266
2361
2267
2362
<step><title>Compile <filename>linux.lisp</filename>, creating
2268
2363
<filename>linux.c</filename></title>
2269
<screen>&sh-prompt; clisp -c /<replaceable>somewhere</replaceable>/bindings/linux.lisp</screen></step>
2364
<screen>&sh-prompt; clisp -c /&path-r;/bindings/linux.lisp</screen></step>
2270
2365
2271
2366
<step><title>Create a new &linkset;</title>
2272
<screen>&sh-prompt; &clisp-link; add-module-set linux base base+linux</screen></step>
2367
<screen>&sh-prompt; &clisp-link; add linux base base+linux</screen></step>
2273
2368
2274
2369
<step><title>Run and try it</title>
2275
2370
<screen>&sh-prompt; base+linux/lisp.run -M base+linux/lispinit.mem -x '(linux:stat "/tmp")'</screen></step>
2276
2371
</procedure>
2277
2372
</example>
2278
2373
</section>
2279
2374
2280
2375
<section id="module-tools"><title>Module tools</title>
2301
2396
(assuming you &export;ed <literal>MY-FUNCTION-NAME</literal> from
2302
2397
<quote role="package">MY-PACKAGE</quote>).</para>
2303
2398
2399
<para>Note that the arguments are passed on the &STACK; (last argument
2400
being the top) which has to be cleaned up before exit.</para>
2401
2304
2402
<para>Another useful macros are:
2305
2403
<variablelist><varlistentry><term><function>DEFVAR</function></term>
2306
2404
<listitem><simpara>create a GC-visible private object
2330
2428
<link linkend="included-modules">included modules</link>, but here are
2331
2429
some important hints that you will need to keep in mind:
2332
2430
<itemizedlist>
2333
<listitem><simpara>Lisp objects have type <type>object</type>.
2334
</simpara></listitem>
2431
<listitem><simpara>Lisp objects have type &object-t;.</simpara></listitem>
2335
2432
<listitem><simpara>Variables of this type are invalidated by
2336
2433
<link linkend="gc-safety">lisp memory allocation</link>
2337
2434
(<function>allocate_*()</function> functions) - but ¬-e; &c-lang;
2338
allocations (<function role="unix">malloc</function> et al) -
2339
and must be saved on the &STACK; using &cpp; macros
2340
<function>pushSTACK()</function>, <function>popSTACK()</function>
2435
allocations (&malloc; et al) - and must be saved on the &STACK; using &cpp;
2436
macros <function>pushSTACK()</function>, <function>popSTACK()</function>
2341
2437
and <function>skipSTACK()</function>.</simpara></listitem>
2342
2438
<listitem><simpara>Access object slots using the
2343
2439
appropriate <function>TheFoo()</function> macro, e.g.,
2349
2445
<literal>begin_system_call()</literal>/<literal>end_system_call()</literal>
2350
2446
pairs. These macros, defined in &clisp-h;, save and restore
2351
2447
registers used by &clisp; which could be clobbered by a system call.
2352
</simpara></listitem>
2353
</itemizedlist>
2448
</simpara><simpara>If the system call could block (e.g., &read-U;)
2449
you need to use <literal>begin_blocking_system_call()</literal> and
2450
<literal>end_blocking_system_call()</literal> instead. This will
2451
allow other threads to run while yours is inside the system call.
2452
This means that &gc;ion could happen while you are inside this system
2453
call and, thus, that all objects of type &object-t; are
2454
invalidated by the call. See also <xref linkend="gc-safety"/> and
2455
<xref linkend="gc-mt"/>.</simpara></listitem></itemizedlist>
2354
2456
</para>
2355
2457
2356
2458
</section>
2373
2475
<para>When deciding how to write a module: whether to use &ffi-pac; or
2374
2476
to stick with &c-lang; and &modprep;, one has to take into account
2375
2477
several issues: <variablelist>
2376
<varlistentry><term>Speed: &c-lang; wins</term>
2478
<varlistentry><term>Speed: &c-lang; wins</term>
2377
2479
<listitem><para>&ffi-pac; has a noticeable overhead:
2378
2480
compare <function>RAWSOCK:HTONS</function> (defined
2379
2481
in <filename role="clisp-cvs">modules/rawsock/rawsock.c</filename>)
2380
2482
with <programlisting language="lisp">
2381
(&def-call-out; htons (:name "htons") (:library :default)
2382
(:arguments (s ffi:short)) (:return-type ffi:short) (:language :stdc))
2483
(&def-call-out; htons (:name "htons") (&library-k; :default)
2484
(&arguments-k; (s ffi:short)) (&ret-type-k; ffi:short) (&lang-k; :stdc))
2383
2485
</programlisting> and observe that <function>RAWSOCK:HTONS</function> is
2384
2486
almost 3 times as fast (this really does compare the &ffi-pac;
2385
2487
overhead to the normal lisp function call because
2388
2490
many times, in which case it would make sense to put the loop itself
2389
2491
into &c-lang;.</para></listitem></varlistentry>
2390
2492
<varlistentry><term>Portability: &c-lang; wins</term>
2391
<listitem><simpara>First of all, &ffi-pac; is ¬-e; as widely ported
2392
as &clisp;, so it is possible that you will face a platform where
2393
&clisp; runs but &ffi-pac; is not present.</simpara>
2394
<simpara>Second, it is much easier to handle portability in &c-lang;:
2395
observe the alternative implementations
2396
of <function role="unix">htonl</function> et al in
2397
<filename role="clisp-cvs">modules/rawsock/rawsock.c</filename>.</simpara>
2398
<simpara>Third, certain &c-lang; structures have different layout on
2399
different platforms, and functions may take 64-bit arguments on some
2400
platforms and 32-bit arguments on others; so the &ffi-pac; code has
2401
to track those differences, while &c-lang; will mostly take care of
2402
these things for you.</simpara>
2403
</listitem></varlistentry>
2493
<listitem><orderedlist><listitem><simpara>&ffi-pac; is ¬-e; as widely
2494
ported as &clisp;, so it is possible that you will face a platform
2495
where &clisp; runs but &ffi-pac; is not present.</simpara></listitem>
2496
<listitem><simpara>It is much easier to handle portability in
2497
&c-lang;: observe the alternative implementations
2498
of <function role="unix">htonl</function> et al in
2499
<filename role="clisp-cvs">modules/rawsock/rawsock.c</filename>.
2500
</simpara></listitem>
2501
<listitem><simpara>Certain &c-lang; structures have different
2502
layout on different platforms, and functions may take 64-bit
2503
arguments on some platforms and 32-bit arguments on others; so the
2504
&ffi-pac; code has to track those differences, while &c-lang; will
2505
mostly take care of these things for you.</simpara></listitem>
2506
</orderedlist></listitem></varlistentry>
2404
2507
<varlistentry><term>Code size: &ffi-pac; wins</term>
2405
2508
<listitem><simpara>You need to type much fewer characters with &ffi-pac;,
2406
2509
and, if you use the &library-k; argument to &def-call-out; and
2425
2528
</simpara></listitem></varlistentry>
2426
2529
<varlistentry><term>Safety: unclear</term>
2427
2530
<listitem><simpara>One can get a segfault either way: if your
2428
&def-call-out; form does not describe the function's expectations
2429
with respect to the arguments and return values (including
2430
&allocation;), you will probably learn that the hard way.
2531
&def-call-out; form does not describe the &c-lang; function's
2532
expectations with respect to the arguments and return values
2533
(including &allocation;), you will probably learn that the hard way.
2431
2534
If the module is written in &c-lang;, all the opportunities to shoot
2432
2535
oneself in the foot (and other body parts) are wide open
2433
2536
(although well known to most &c-lang; users).
2453
2556
particular <emphasis>binary</emphasis> distribution).</para>
2454
2557
2455
2558
<para>To use modules, read <filename role="clisp-cvs">unix/INSTALL</filename>
2456
and build &clisp; in directory <filename>build-dir</filename> with,
2559
and build &clisp; in a directory <filename>build-dir</filename> with,
2457
2560
e.g.,<screen>
2458
&sh-prompt; ./configure --with-module=pcre --with-module=clx/new-clx --build build-dir
2459
</screen>then run it with
2561
&sh-prompt; ./configure --with-module=pcre --with-module=clx/new-clx --cbc build-dir</screen> then run it with
2460
2562
<screen>&sh-prompt; ./build-dir/clisp &opt-K; full</screen>
2461
2563
This will create a &base; &linkset; with modules
2462
2564
&i18n-mod;, ®exp-mod; and &syscalls-mod; (and maybe &readline-mod;);
2463
2565
and a &full; &linkset; with modules &new-clx; and &pcre-mod; in addition
2464
to the 3 (or 4) <link linkend="base-modules">base modules</link>.</para>
2566
to the 3 (or 4) &base; modules.</para>
2465
2567
2466
2568
<para>Here we list the included modules by their general theme.
2467
2569
See <xref linkend="ext-modules"/> for individual module documentation.</para>
2473
2575
<listitem><simpara>Internationalization of User Programs.
2474
2576
</simpara></listitem></varlistentry>
2475
2577
<varlistentry><term>®exp-mod;</term>
2476
<listitem><simpara>The <ulink url="regexp.html">POSIX Regular
2578
<listitem><simpara>The &posix; <ulink url="regexp.html">Regular
2477
2579
Expressions</ulink> matching, compiling, executing.
2478
2580
</simpara></listitem></varlistentry>
2479
2581
<varlistentry><term>&syscalls-mod;</term>
2495
2597
<email>masayuki.onjo@gmail.com</email></author>.
2496
2598
</simpara></listitem></varlistentry>
2497
2599
<varlistentry><term>&berkeley-db-mod;</term>
2498
<listitem><simpara><ulink role="bdb" url="index.html">Berkeley DB
2499
from Sleepycat Software</ulink> interface.
2500
</simpara></listitem></varlistentry>
2600
<listitem><simpara><ulink role="bdb" url="index.html">Berkeley DB</ulink>
2601
interface.</simpara></listitem></varlistentry>
2501
2602
<varlistentry><term>&dirkey-mod;</term>
2502
2603
<listitem><simpara>Directory Access (LDAP, &win32; registry etc).
2503
2604
</simpara></listitem></varlistentry>
2505
2606
<listitem><simpara>Access &postgresql-link; from &clisp;.
2506
2607
</simpara></listitem></varlistentry>
2507
2608
<varlistentry><term>&oracle-mod;</term>
2508
<listitem><simpara>Access
2509
<ulink url="http://www.oracle.com/">Oracle</ulink> from &clisp;;
2510
by &hin;.</simpara></listitem></varlistentry>
2609
<listitem><simpara>Access &oracle-link; RDBMS from &clisp;; by &hin;.
2610
</simpara></listitem></varlistentry>
2511
2611
</variablelist></section>
2512
2612
2513
2613
<section id="incmod-kdml"><title>Mathematics, Data Mining et al</title>
2514
2614
<variablelist><varlistentry><term>&libsvm-mod;</term>
2515
<listitem><simpara>Build <ulink url="http://www.kernel-machines.org/">Support
2615
<listitem><simpara>Build
2616
<ulink url="http://www.support-vector-machines.org/">Support
2516
2617
Vector Machine</ulink> models using &libsvm-link; inside &clisp;.
2517
2618
</simpara></listitem></varlistentry>
2518
2619
<varlistentry><term>&pari-mod;</term>
2529
2630
2530
2631
<section id="incmod-match"><title>Matching, File Processing et al</title>
2531
2632
<variablelist><varlistentry><term>&pcre-mod;</term>
2532
<listitem><simpara>The <ulink url="http://www.pcre.org/">Perl
2533
Compatible Regular Expressions</ulink> matching, compiling,
2534
executing.</simpara></listitem></varlistentry>
2633
<listitem><simpara>The &pcre-link; matching, compiling, executing.
2634
</simpara></listitem></varlistentry>
2535
2635
<varlistentry><term>&wildcard-mod;</term>
2536
2636
<listitem><simpara>Shell (&sh;) globbing (&path-match;).
2537
2637
</simpara></listitem></varlistentry>
2538
2638
<varlistentry><term>&zlib-mod;</term>
2539
<listitem><simpara>Compress &vector-t;s using
2540
<ulink url="http://www.zlib.org">ZLIB</ulink>.
2639
<listitem><simpara>Compress &vector-t;s using &zlib-link;.
2541
2640
</simpara></listitem></varlistentry>
2542
2641
</variablelist></section>
2543
2642
2544
<section id="incmod-net"><title>Networking</title>
2643
<section id="incmod-net"><title>Communication, Networking</title>
2545
2644
<variablelist><varlistentry><term>&rawsock-mod;</term>
2546
2645
<listitem><simpara>Raw socket access.</simpara></listitem></varlistentry>
2646
<varlistentry><term>&dbus-mod;</term>
2647
<listitem><simpara>Interface to &d-bus-link;.
2648
</simpara></listitem></varlistentry>
2547
2649
<varlistentry><term>&fastcgi-mod;</term>
2548
<listitem><simpara>Access
2549
<ulink url="http://www.fastcgi.com/">FastCGI</ulink> from &clisp;;
2650
<listitem><simpara>Access &fastcgi-link; from &clisp;;
2550
2651
by &hin;.</simpara></listitem></varlistentry>
2551
2652
</variablelist></section>
2552
2653
2553
2654
<section id="incmod-gui"><title>Graphics</title>
2554
2655
<variablelist><varlistentry><term>&clx;</term>
2555
2656
<listitem><para>Call
2556
<ulink url="http://www.the-labs.com/X11/XLib-Manual/">Xlib</ulink>
2557
functions from &clisp;. Two implementations are supplied:
2657
<ulink url="http://www.x.org/docs/X11/xlib.pdf">Xlib</ulink>
2658
functions from &clisp;. Two implementations are supplied:
2558
2659
<variablelist><varlistentry><term>&mit-clx;, from MIT
2559
2660
<ulink url="ftp://ftp.x.org/R5contrib/CLX.R5.02.tar.Z"/></term>
2560
2661
<listitem><simpara>the standard implementation
2614
2715
and to do many related things, like inspect and modify foreign memory,
2615
2716
define a <quote>callback</quote> (i.e., make a lisp function available
2616
2717
to the &c-lang; world), etc.
2617
To use this facility, one writes a foreign function description into an
2618
ordinary Lisp file, which is then compiled and loaded as usual.</para>
2718
To use this facility, one writes a <firstterm>foreign function
2719
<indexterm id="dffi-ff"><primary>foreign function</primary>
2720
</indexterm></firstterm> description into an
2721
ordinary Lisp file, which is then compiled and loaded as usual;
2722
or just evaluates the appropriate form in the &repl;.</para>
2619
2723
2620
2724
<para>There are two basic ways to do define a foreign function:<orderedlist>
2621
<listitem><simpara>Use <function role="unix">dlopen</function> and
2622
<function role="unix">dlsym</function> to get to the location of the
2725
<listitem><simpara>Use &dlopen; and &dlsym; to get to the location of the
2623
2726
function code in a dynamic library.
2624
2727
To access this facility, pass the &library-k; option to &def-call-out;
2625
and &def-c-var;.
2626
Unfortunately, this functionality is not available on some operating
2627
systems, and, also, it offers only a part of the foreign functionality:
2628
&cpp; macros and <literal>inline</literal> functions cannot be
2629
accessed this way.</simpara></listitem>
2728
and &def-c-var;.</simpara>
2729
<simpara>Unfortunately, this functionality is not available on some
2730
operating systems, and, also, it offers only a part of the foreign
2731
functionality: &cpp; macros and <literal>inline</literal> functions
2732
cannot be accessed this way. On the other hand, this functionality
2733
is available in the &repl; and does not require a &c-lang; compiler.
2734
</simpara></listitem>
2630
2735
<listitem><simpara>Use a somewhat less direct way: when you do not use
2631
the &library-k; argument, &compile-file-my; produces a &c-file; file (in
2632
addition to a &fasl-file; and a &lib-file;).
2736
the &library-k; argument, &compile-file-my; produces a &c-file; file
2737
(in addition to a &fasl-file; and a &lib-file;).
2633
2738
Then you compile (with a &c-lang; compiler) and link it into &clisp;
2634
2739
(statically, linking it into <filename>lisp.a</filename>, or
2635
dynamically, loading it into a running &clisp; using
2636
<function role="unix">dlopen</function> and
2637
<function role="unix">dlsym</function>).
2740
dynamically, loading it into a running &clisp; using &dlopen; and &dlsym;).
2638
2741
This way you can use any functionality your foreign library exports,
2639
2742
whether using ordinary functions, <literal>inline</literal> functions,
2640
2743
or &cpp; macros (see <xref linkend="dffi-ex-macro"/>).
2642
2745
</para>
2643
2746
2644
2747
<para>All symbols relating to the foreign function interface are
2645
exported from the package &ffi-pac;. To use them,
2646
<code>(&use-package; &ffi-pac;)</code>.</para>
2748
exported from the package &ffi-pac;.
2749
To use them, <code>(&use-package; &ffi-pac;)</code>.</para>
2647
2750
2648
2751
<para>Special &ffi-pac; forms may appear anywhere in the Lisp file.</para>
2649
2752
2656
2759
and &the-ansi; &c-lang;.</para>
2657
2760
2658
2761
<note><simpara>Unless specifically noted otherwise, type specification
2659
parameters are not evaluated, so that they can be compiled by
2762
parameters are ¬-e; evaluated, so that they can be compiled by
2660
2763
&parse-c-type; into the internal format at macroexpansion time.
2661
2764
</simpara></note>
2662
2765
2705
2808
<listitem><simpara>Specifies the (optional) dynamic library
2706
2809
which contains the variable, the default is set by
2707
2810
&default-foreign-library;.</simpara></listitem></varlistentry>
2811
<varlistentry><term><code>(&version-k; &version-r;)</code></term>
2812
<listitem><simpara>Specifies the (optional) symbol version in the library
2813
(therefore, if &version-k; is supplied, &library-k; must also be supplied)
2814
</simpara></listitem></varlistentry>
2708
2815
<varlistentry><term><code>(&documentation-k; &string-r;)</code></term>
2709
2816
<listitem><simpara>Specifies the (optional) &variable-doc; documentation.
2710
2817
</simpara></listitem></varlistentry>
2762
2869
<varlistentry><term><code>(&library-k; &name-r;)</code></term>
2763
2870
<listitem><simpara>Specifies the (optional) dynamic library
2764
2871
which contains the function, the default is set by
2765
&default-foreign-library;</simpara></listitem></varlistentry>
2872
&default-foreign-library;.</simpara></listitem></varlistentry>
2873
<varlistentry><term><code>(&version-k; &version-r;)</code></term>
2874
<listitem><simpara>Specifies the (optional) symbol version in the library
2875
(therefore, if &version-k; is supplied, &library-k; must also be supplied)
2876
</simpara></listitem></varlistentry>
2766
2877
<varlistentry><term><code>(&documentation-k; &string-r;)</code></term>
2767
2878
<listitem><simpara>Specifies the (optional) &function-doc; documentation.
2768
</simpara></listitem></varlistentry>
2769
</variablelist></listitem></varlistentry>
2879
</simpara></listitem></varlistentry></variablelist>
2880
<simpara>See also <xref linkend="dffi-functions"/>.</simpara>
2881
</listitem></varlistentry>
2770
2882
2771
2883
<varlistentry id="def-call-in"><term><code>(&def-call-in;
2772
&name-r; {&option-r;}*)</code></term>
2773
<listitem><simpara>This form defines a named call-in function (i.e., a Lisp
2774
function called from the foreign language: control flow temporary
2775
enters Lisp)</simpara><variablelist id="def-call-in-opts">
2884
&func-r; {&option-r;}*)</code></term>
2885
<listitem><simpara>This form defines a
2886
<firstterm>callback<indexterm id="def-call-in-callback">
2887
<primary>callback</primary></indexterm></firstterm> -
2888
a named call-in function (i.e., a Lisp function called from the
2889
foreign language: control flow temporary enters Lisp)</simpara>
2890
<variablelist id="def-call-in-opts">
2776
2891
<title>Options for &def-call-in;</title>
2777
2892
<varlistentry><term><code>(&name-k; &cname-r;)</code></term>
2778
2893
<listitem><simpara>Any &c-lang; function call to the &c-lang; function
2779
&cname-r; is redirected to call the &cl; function
2780
<function>#'&name-r;</function>.</simpara></listitem></varlistentry>
2894
&cname-r; is redirected to call the &cl; function &func-r;, which
2895
should be a &funname;.</simpara></listitem></varlistentry>
2781
2896
<varlistentry><term><code>(&arguments-k;
2782
2897
{(&arg-r; &ctype-r; [¶m-mode; [&allocation;]])}*)</code></term>
2783
2898
<term><code>(&ret-type-k; &ctype-r; [&allocation;])</code></term>
2786
2901
</simpara></listitem></varlistentry>
2787
2902
<varlistentry><term><code>(&lang-k; &lang-r;)</code></term>
2788
2903
<listitem><simpara>See <xref linkend="c-flavor"/>.
2789
</simpara></listitem></varlistentry></variablelist></listitem></varlistentry>
2904
</simpara></listitem></varlistentry></variablelist>
2905
<simpara>See also <xref linkend="dffi-functions"/>.</simpara>
2906
</listitem></varlistentry>
2907
2908
<varlistentry id="dffi-open-lib"><term><code>(&open-foreign-library;
2909
&name-r;)</code></term>
2910
<listitem><simpara>Open (load) a shared foreign library.</simpara>
2911
<simpara>This is only needed if you want to test
2912
for <emphasis>presence</emphasis> of a library without creating a
2913
foreign object. When you create a &foreign-variable-t; or a
2914
&foreign-function-t; using &def-c-var; or &def-call-out; with a
2915
&library-k; argument, the library &name-r; is opened automatically.
2916
</simpara></listitem></varlistentry>
2790
2917
2791
2918
<varlistentry id="dffi-close-lib"><term><code>(&close-foreign-library;
2792
2919
&name-r;)</code></term>
2793
<listitem><simpara>Close (unload) a shared foreign library (opened by the
2794
&library-k; argument to &def-call-out; or &def-c-var;).</simpara>
2920
<listitem><simpara>Close (unload) a shared foreign library (opened by
2921
&open-foreign-library; or the &library-k; argument to &def-call-out;
2922
or &def-c-var;).</simpara>
2795
2923
<simpara>If you modify your shared library, you need to use close it
2796
using &close-foreign-library; first. When you try to use the
2924
using &close-foreign-library; first. When you use the
2797
2925
&foreign-variable-t; or the &foreign-function-t; which resides in the
2798
2926
library &name-r;, it will be re-opened automatically.
2799
2927
</simpara></listitem></varlistentry>
2803
2931
<listitem><simpara>This macro sets the default &library-k; argument for
2804
2932
&def-call-out; and &def-c-var;. &lib-name; should be &nil;
2805
2933
(meaning use the &c-lang; file produced by &compile-file-my;), a
2806
&string-t;, or, depending on the
2807
underlying <function role="unix">dlsym</function> implementation,
2934
&string-t;, or, depending on the underlying &dlsym;
2935
or <function role="bsd">dlvsym</function> implementation,
2808
2936
&default-k; or <constant>:NEXT</constant>.</simpara>
2809
2937
<simpara>The default is set separately in each &comp-unit;, so, if you
2810
2938
are interfacing to a single library, you can set this variable in the
2828
2956
<listitem><simpara>means that the name of this structure is a
2829
2957
&c-lang; type defined with <function>typedef</function>
2830
2958
elsewhere.</simpara></listitem></varlistentry>
2831
<varlistentry id="def-c-struct-external">
2832
<term><constant>:EXTERNAL</constant></term>
2959
<varlistentry id="def-c-struct-external"><term>&external-k;</term>
2833
2960
<listitem><simpara>means that this structure is defined in a
2834
&c-file; file that you include with, e.g.,
2961
&c-lang; header file that you include with, e.g.,
2835
2962
<code>(&c-lines; "#include <filename.h>~%")</code>.
2836
2963
</simpara></listitem></varlistentry></variablelist>
2837
2964
These options determine how the struct is written to the &c-file;.
2870
2997
function</link></simpara></listitem></varlistentry>
2871
2998
</variablelist></para></listitem></varlistentry>
2872
2999
2873
<varlistentry id="element"><term><code>(&element;
2874
&cplace-r; <replaceable>index&sub-1;</replaceable> ...
2875
<replaceable>index&sub-n;</replaceable>)</code></term>
2876
<listitem><simpara>Array element: If &cplace-r; is of foreign type
2877
<literal role="type">(&c-array; &ctype-r;
2878
(<replaceable>dim&sub-1;</replaceable>
2879
... <replaceable>dim&sub-n;</replaceable>))</literal>
2880
and 0 ≤ <replaceable>index&sub-1;</replaceable>
2881
< <replaceable>dim&sub-1;</replaceable>, ..., 0
2882
≤ <replaceable>index&sub-n;</replaceable> <
2883
<replaceable>dim&sub-n;</replaceable>, this will be
2884
the &place; corresponding to <code>(&aref;
2885
&cplace-r; <replaceable>index&sub-1;</replaceable>
2886
... <replaceable>index&sub-n;</replaceable>)</code> or
2887
<varname>&cplace-r;[<replaceable>index&sub-1;</replaceable>]...[<replaceable>index&sub-n;</replaceable>]</varname>.
2888
It is a &place; of type &ctype-r;.
2889
If &cplace-r; is of foreign type <literal role="type">(&c-array-max;
2890
&ctype-r; &dim-r;)</literal> and 0 ≤ &index-r; < &dim-r;,
2891
this will be the &place; corresponding to <code>(&aref; &cplace-r;
2892
&index-r;)</code> or <varname>&cplace-r;[&index-r;]</varname>.
2893
It is a &place; of type &ctype-r;.
3000
<varlistentry id="element"><term><code>(&element; &cplace-r; &index1-r;
3001
... &indexn-r;)</code></term>
3002
<listitem><simpara>Array element: If &cplace-r; is of foreign type
3003
<literal role="type">(&c-array; &ctype-r; (&dim1-r; ... &dimn-r;))</literal>
3004
and 0 ≤ &index1-r; < &dim1-r;, ..., 0 ≤ &indexn-r; < &dimn-r;,
3005
this will be the &place; corresponding to <code>(&aref; &cplace-r;
3006
&index1-r; ... &indexn-r;)</code> or
3007
<varname>&cplace-r;[&index1-r;]...[&indexn-r;]</varname>.
3008
It is a &place; of type &ctype-r;.
3009
If &cplace-r; is of foreign type <literal role="type">(&c-array-max;
3010
&ctype-r; &dim-r;)</literal> and 0 ≤ &index-r; < &dim-r;,
3011
this will be the &place; corresponding to <code>(&aref; &cplace-r;
3012
&index-r;)</code> or <varname>&cplace-r;[&index-r;]</varname>.
3013
It is a &place; of type &ctype-r;.
2894
3014
</simpara></listitem></varlistentry>
2895
3015
2896
3016
<varlistentry id="deref"><term><code>(&deref; &cplace-r;)</code></term>
2964
3084
&c-lang; type of &cplace-r;, measured in bits.
2965
3085
</simpara></listitem></varlistentry>
2966
3086
2967
<varlistentry id="fa-null">
2968
<term><code>(&foreign-address-null; &f-ent;)</code></term>
2969
<listitem><simpara>This predicate returns &t; if the
2970
&f-ent; refers to the &c-NULL; address (and thus &f-ent; should
2971
probably not be passed to most foreign functions).
2972
</simpara></listitem></varlistentry>
2973
2974
3087
<varlistentry id="faddr-u">
2975
3088
<term><code>(&foreign-address-unsigned; &f-ent;)</code></term>
2976
3089
<term><code>(&unsigned-foreign-address; &number-r;)</code></term>
3021
3134
<code>(&parse-c-type; '(&c-function; ...))</code>,
3022
3135
in which case it is important to specify the &lang-k; because the
3023
3136
expressions are likely to be evaluated at run time, outside the &comp-unit;).
3024
&name-r;, a &string-t;, is mostly useful for documentation and
3137
The &name-r;, a &string-t;, is mostly useful for documentation and
3025
3138
interactive debugging since it appears in the printed representation
3026
of the &foreign-function-t; object, as in
3139
of the &foreign-function-t; object, e.g.,
3027
3140
<computeroutput>#<&foreign-function-t; "foo"
3028
3141
#x0052B060></computeroutput>.
3029
3142
It is inherited from the given &foreign-function-t; object when
3030
available.</simpara></listitem></varlistentry>
3143
available.</simpara>
3144
<simpara>See also <xref linkend="dffi-functions"/>.</simpara>
3145
</listitem></varlistentry>
3031
3146
3032
3147
<varlistentry id="validp"><term><code>(&validp; &f-ent;)</code></term>
3033
3148
<term><code>(&setf; (&validp; &f-ent;) &value-r;)</code></term>
3067
3182
stack, bind respectively a &foreign-variable-t; object or
3068
3183
a local &symbol-macro; to &var-r; and execute &body-r;.</simpara>
3069
3184
<simpara>When <replaceable>initarg</replaceable> is not supplied,
3070
they allocate space only for <code>(&sizeof;
3071
&ctype-r;)</code> bytes. This space is filled with zeroes. E.g.,
3185
they allocate space only for <code>(&sizeof; &ctype-r;)</code> bytes.
3186
This space is filled with zeroes. E.g.,
3072
3187
using a &ctype-r; of &c-string; or even <literal role="type">(&c-ptr;
3073
3188
(&c-array; <type>uint8</type> 32))</literal> (!) both allocate space
3074
3189
for a single pointer, initialized to &c-NULL;.</simpara>
3162
3277
is used instead.
3163
3278
When &ro-k; is supplied, the Lisp side is prevented from modifying the
3164
3279
memory contents. This can be used as an indication that some foreign
3165
side is going to fill this memory
3166
(e.g. via <function role="unix">read</function>).</simpara>
3280
side is going to fill this memory (e.g. via &read-U;).</simpara>
3167
3281
<simpara>Returns a &foreign-variable-t; object of the actual &ctype-r;,
3168
3282
whose address part points to the newly allocated memory.</simpara>
3169
3283
<simpara>&allocate-deep; will call &c-lang; &malloc; as many times
3226
3340
&clisp; will guard the &c-lang; statements in the output file with
3227
3341
&cpp; conditionals to take advantage of &autoconf; feature detection.
3228
3342
E.g., <programlisting language="lisp">
3229
(eval-when (compile) (setq *foreign-guard* t))
3230
(def-call-out some-function (:name "function_name") ...)
3343
(&eval-when; (compile) (setq *foreign-guard* t))
3344
(&def-call-out; some-function (:name "function_name") ...)
3231
3345
</programlisting> will produce <programlisting language="C">
3232
3346
# if defined(HAVE_FUNCTION_NAME)
3233
3347
register_foreign_function((void*)&function_name,"function_name",1024);
3239
3353
<simpara>&ffi-guard; is initialized to &nil; for backwards compatibility.
3240
3354
</simpara></listitem></varlistentry>
3241
3355
3356
<varlistentry id="fptr-info"><term>&foreign-pointer-info;</term>
3357
<listitem><simpara>This is an interface
3358
to <function role="bsd">dladdr</function> and it returns the 4 fields
3359
of <type>Dl_info</type> as &mul-val;.</simpara></listitem>
3360
</varlistentry>
3361
3242
3362
</variablelist>
3243
3363
3244
3364
<variablelist id="dffi-low"><title>Low-level &ffi-pac; forms</title>
3358
3478
a string, without the trailing zero character.
3359
3479
</simpara></listitem></varlistentry>
3360
3480
3361
<varlistentry id="c-struct"><term><literal role="type">(&c-struct;
3362
&class-r; (<replaceable>ident&sub-1;</replaceable>
3363
<replaceable>c-type&sub-1;</replaceable>) ...
3364
(<replaceable>ident&sub-n;</replaceable>
3365
<replaceable>c-type&sub-n;</replaceable>))</literal></term>
3481
<varlistentry id="c-struct"><term><literal role="type">(&c-struct; &class-r;
3482
(&ident1-r; &ctype1-r;) ... (&identn-r; &ctypen-r;))</literal></term>
3366
3483
<listitem><simpara>This type is equivalent to what &c-lang; calls
3367
<type>struct { <replaceable>c-type&sub-1;</replaceable>
3368
<replaceable>ident&sub-1;</replaceable>; ...;
3369
<replaceable>c-type&sub-n;</replaceable>
3370
<replaceable>ident&sub-n;</replaceable>; }</type>.
3371
Its Lisp equivalent is: if &class-r; is &vector-t;, a
3372
&simple-vector-t;; if &class-r; is &list-t;, a &proper-list-glo;;
3373
if &class-r; is a symbol naming a structure or &clos; class, an
3374
instance of this class, with slots of names
3375
<replaceable>ident&sub-1;</replaceable>, ...,
3376
<replaceable>ident&sub-n;</replaceable>.</simpara><simpara>
3377
&class-r; may also be a &cons-t; of a &symbol-t; (as above) and
3378
a &list-t; of &def-c-struct; options.
3379
</simpara></listitem></varlistentry>
3484
<type>struct { &ctype1-r; &ident1-r;; ...; &ctypen-r; &identn-r;; }</type>.
3485
Its Lisp equivalent is: if &class-r; is &vector-t;, a
3486
&simple-vector-t;; if &class-r; is &list-t;, a &proper-list-glo;;
3487
if &class-r; is a symbol naming a structure or &clos; class, an
3488
instance of this class, with slots of names
3489
&ident1-r;, ..., &identn-r;.</simpara><simpara>
3490
&class-r; may also be a &cons-t; of a &symbol-t; (as above) and
3491
a &list-t; of &def-c-struct; options.
3492
</simpara></listitem></varlistentry>
3380
3493
3381
3494
<varlistentry id="c-union"><term><literal role="type">(&c-union;
3382
(<replaceable>ident&sub-1;</replaceable>
3383
<replaceable>c-type&sub-1;</replaceable>) ...
3384
(<replaceable>ident&sub-n;</replaceable>
3385
<replaceable>c-type&sub-n;</replaceable>))</literal></term>
3495
(&ident1-r; &ctype1-r;) ... (&identn-r; &ctypen-r;))</literal></term>
3386
3496
<listitem><simpara>This type is equivalent to what &c-lang; calls
3387
<type>union { <replaceable>c-type&sub-1;</replaceable>
3388
<replaceable>ident&sub-1;</replaceable>; ...;
3389
<replaceable>c-type&sub-n;</replaceable>
3390
<replaceable>ident&sub-n;</replaceable>;
3391
}</type>.
3392
Conversion to and from Lisp assumes that a value is to be viewed as
3393
being of <replaceable>c-type&sub-1;</replaceable>.
3394
</simpara></listitem></varlistentry>
3497
<type>union { &ctype1-r; &ident1-r;; ...; &ctypen-r; &identn-r;; }</type>.
3498
Conversion to and from Lisp assumes that a value is to be viewed as
3499
being of &ctype1-r;.
3500
</simpara></listitem></varlistentry>
3395
3501
3396
3502
<varlistentry id="c-array"><term><literal role="type">(&c-array;
3397
&ctype-r; <replaceable>dim&sub-1;</replaceable>)</literal></term>
3398
<term><literal role="type">(&c-array;
3399
&ctype-r; (<replaceable>dim&sub-1;</replaceable> ...
3400
<replaceable>dim&sub-n;</replaceable>))</literal></term>
3503
&ctype-r; &dim1-r;)</literal></term>
3504
<term><literal role="type">(&c-array; &ctype-r; (&dim1-r;
3505
... &dimn-r;))</literal></term>
3401
3506
<listitem><simpara>This type is equivalent to what &c-lang; calls
3402
<type>&ctype-r; [<replaceable>dim&sub-1;</replaceable>]
3403
... [<replaceable>dim&sub-n;</replaceable>]</type>.
3404
Note that when an array is passed as an argument to a function in
3405
&c-lang;, it is actually passed as a pointer; you therefore have to
3406
write <literal role="type">(&c-ptr; (&c-array; ...))</literal> for this
3407
argument's type.</simpara></listitem></varlistentry>
3507
<type>&ctype-r; [&dim1-r;] ... [&dimn-r;]</type>.
3508
Note that when an array is passed as an argument to a function in
3509
&c-lang;, it is actually passed as a pointer; you therefore have to
3510
write <literal role="type">(&c-ptr; (&c-array; ...))</literal> for this
3511
argument's type.</simpara></listitem></varlistentry>
3408
3512
3409
3513
<varlistentry id="c-array-max"><term><literal role="type">(&c-array-max;
3410
&ctype-r; &maxdim-r;)</literal></term>
3514
&ctype-r; &maxdim-r;)</literal></term>
3411
3515
<listitem><simpara>This type is equivalent to what &c-lang; calls
3412
<type>&ctype-r; [&maxdim-r;]</type>, an array containing up to
3413
&maxdim-r; elements.
3414
The array is zero-terminated if it contains less than &maxdim-r; elements.
3415
Conversion from Lisp of an array with more than &maxdim-r; elements
3416
silently ignores the superfluous elements.
3417
</simpara></listitem></varlistentry>
3516
<type>&ctype-r; [&maxdim-r;]</type>, an array containing up to
3517
&maxdim-r; elements.
3518
The array is zero-terminated if it contains less than &maxdim-r; elements.
3519
Conversion from Lisp of an array with more than &maxdim-r; elements
3520
silently ignores the extra elements.
3521
</simpara></listitem></varlistentry>
3418
3522
3419
3523
<varlistentry id="c-function"><term><literal
3420
3524
role="type">(&c-function; (&arguments-k;
3430
3534
is transparent, and &c-NULL;/&nil; is recognized and
3431
3535
accepted.</simpara></listitem></varlistentry>
3432
3536
3433
<varlistentry id="c-ptr"><term><literal role="type">(&c-ptr;
3434
&ctype-r;)</literal></term>
3537
<varlistentry id="c-ptr">
3538
<term><literal role="type">(&c-ptr; &ctype-r;)</literal></term>
3435
3539
<listitem><simpara>This type is equivalent to what &c-lang; calls
3436
<type>&ctype-r; *</type>: a pointer to a single item of the given
3437
&ctype-r;.</simpara></listitem></varlistentry>
3540
<type>&ctype-r; *</type>: a pointer to a single item of the given
3541
&ctype-r;.</simpara></listitem></varlistentry>
3438
3542
3439
<varlistentry id="c-ptr-null"><term><literal
3440
role="type">(&c-ptr-null; &ctype-r;)</literal></term>
3543
<varlistentry id="c-ptr-null">
3544
<term><literal role="type">(&c-ptr-null; &ctype-r;)</literal></term>
3441
3545
<listitem><simpara>This type is also equivalent to what &c-lang; calls
3442
<type>&ctype-r; *</type>: a pointer to a single item of the given
3443
&ctype-r;, with the exception that &c-lang; &c-NULL; corresponds to
3444
Lisp &nil;.</simpara></listitem></varlistentry>
3546
<type>&ctype-r; *</type>: a pointer to a single item of the given
3547
&ctype-r;, with the exception that &c-lang; &c-NULL; corresponds to
3548
Lisp &nil;.</simpara></listitem></varlistentry>
3445
3549
3446
<varlistentry id="c-array-ptr"><term><literal
3447
role="type">(&c-array-ptr; &ctype-r;)</literal></term>
3550
<varlistentry id="c-array-ptr">
3551
<term><literal role="type">(&c-array-ptr; &ctype-r;)</literal></term>
3448
3552
<listitem><simpara>This type is equivalent to what &c-lang; calls
3449
<type>&ctype-r; (*)[]</type>: a pointer to a zero-terminated array of
3450
items of the given &ctype-r;.</simpara></listitem></varlistentry>
3553
<type>&ctype-r; (*)[]</type>: a pointer to a zero-terminated array of
3554
items of the given &ctype-r;.</simpara></listitem></varlistentry>
3451
3555
</variablelist>
3452
3556
3453
3557
<!-- #ifdef UNICODE -->
3454
3558
<para>The conversion of &c-string;,
3455
<literal role="type">(&c-array; &character-t; <replaceable>dim&sub-1;</replaceable>)</literal>,
3559
<literal role="type">(&c-array; &character-t; &dim1-r;)</literal>,
3456
3560
<literal role="type">(&c-array-max; &character-t; &maxdim-r;)</literal>,
3457
3561
<literal role="type">(&c-array-ptr; &character-t;)</literal>
3458
3562
is governed by &foreign-enc; and dimensions are given
3461
3565
<literal role="type">(&c-ptr; &character-t;)</literal>, or
3462
3566
<literal role="type">(&c-ptr-null; &character-t;)</literal>, as well as
3463
3567
that of multi-dimensional arrays <literal role="type">(&c-array; &character-t;
3464
(<replaceable>dim&sub-1;</replaceable> ... <replaceable>dim&sub-n;</replaceable>))</literal>,
3465
are governed by &foreign-enc; if the latter is a 1:1 encoding, or by the
3466
&ascii; encoding otherwise.</para>
3568
(&dim1-r; ... &dimn-r;))</literal>, are governed by &foreign-enc; if
3569
the latter is a &enc1-1;, or by the &ascii; encoding otherwise.</para>
3467
3570
<!-- #endif -->
3468
3571
<note><para>Remember that the &c-lang; type <type>char</type> is
3469
3572
a <emphasis>numeric</emphasis> type and does not use &character-t;
3476
3579
<para>&c-function;, &def-call-in;, &def-call-out; take a &lang-k; argument.
3477
3580
The &lang-r; is either &c-k; (denotes K&R &c-lang;) or &stdc-k;
3478
3581
(denotes &the-ansi; &c-lang;) or &stdc-sc-k; (denotes &the-ansi; &c-lang;
3479
with the <quote role="dict">stdcall</quote> calling convention).
3582
with the <ulink url="google">stdcall</ulink> calling convention).
3480
3583
It specifies whether the &c-lang; function (caller or callee) has been
3481
3584
compiled by a K&R &c-lang; compiler or by an &the-ansi; &c-lang; compiler,
3482
3585
and possibly the calling convention.</para>
3483
3586
3484
3587
<para>The default language is set using the macro
3485
<firstterm><function>FFI:DEFAULT-FOREIGN-LANGUAGE</function>
3588
<firstterm>&default-foreign-language;
3486
3589
<indexterm id="dflt-ffi-lang" significance="preferred">
3487
<primary id="dflt-ffi-lang-i"><function>DEFAULT-FOREIGN-LANGUAGE</function>
3590
<primary><function>DEFAULT-FOREIGN-LANGUAGE</function>
3488
3591
</primary></indexterm></firstterm>.
3489
3592
If this macro has not been called in the current &comp-unit;
3490
(usually a file), a warning is issued and
3491
&stdc-k; is used for the rest of the unit.</para></section>
3593
(usually a file), a warning is issued and &stdc-k; is used for the rest
3594
of the unit.</para></section>
3492
3595
3493
3596
<section id="dffi-variables"><title>Foreign variables</title>
3494
3597
3495
<para>Foreign variables are variables whose storage is allocated in the
3496
foreign language module.
3598
<para><firstterm>Foreign variables<indexterm id="dffi-fv"><primary>foreign
3599
variable</primary></indexterm></firstterm> are variables whose
3600
storage is allocated in the foreign language module.
3497
3601
They can nevertheless be evaluated and modified through &setq;,
3498
3602
just as normal variables can, except that the range of allowed values
3499
3603
is limited according to the variable's foreign type.</para>
3500
3604
3501
<warning id="dffi-eq"><title>Equality of foreign values.</title>
3605
<warning id="dffi-eq"><title>Equality of foreign values</title>
3502
3606
<simpara>For a foreign variable &x-r; the form <code>(&eql; &x-r;
3503
3607
&x-r;)</code> is not necessarily true, since every time &x-r; is
3504
3608
evaluated its foreign value is converted to a &fresh; Lisp value.
3528
3632
3529
3633
<section id="dffi-functions"><title>Foreign functions</title>
3530
3634
3531
<para>Foreign functions are functions which are defined in the foreign
3532
language. There are <firstterm>named foreign functions</firstterm>
3635
<para>Foreign functions are functions which are defined in the foreign language.
3636
There are <firstterm>named foreign functions<indexterm id="dffi-ff-n">
3637
<primary>foreign function</primary><secondary>named</secondary>
3638
</indexterm></firstterm>
3533
3639
(imported via &def-call-out; or created via &def-call-in;) and
3534
<firstterm>anonymous foreign functions</firstterm>; they arise through
3535
conversion of function pointers.</para>
3640
<firstterm>anonymous foreign functions<indexterm id="dffi-ff-a">
3641
<primary>foreign function</primary><secondary>anonymous</secondary>
3642
</indexterm></firstterm>; they arise through conversion of function
3643
pointers using &foreign-function;.</para>
3536
3644
3537
<para>A <firstterm>call-out function</firstterm> is a foreign function
3645
<para>A <firstterm>call-out function<indexterm id="dffi-ff-call-out">
3646
<primary>foreign function</primary><secondary>call-out</secondary>
3647
</indexterm></firstterm> is a foreign function
3538
3648
called from Lisp: control flow temporarily leaves Lisp.
3539
A <firstterm>call-in function</firstterm> is a Lisp function called
3540
from the foreign language: control flow temporary enters Lisp.</para>
3649
A <firstterm>call-in function<indexterm id="dffi-ff-call-in">
3650
<primary>foreign function</primary><secondary>call-in</secondary>
3651
</indexterm></firstterm>
3652
(AKA <firstterm>callback<indexterm id="def-call-in-callback-main" significance="preferred"><primary>callback</primary></indexterm></firstterm>)
3653
is a Lisp function called from the foreign language:
3654
control flow temporary enters Lisp.</para>
3541
3655
3542
3656
<para>The following operators define foreign functions:
3543
<simplelist columns="2"><member>&def-call-in;</member>
3657
<simplelist columns="1"><member>&def-call-in;</member>
3544
3658
<member>&def-call-out;</member><member>&foreign-function;</member>
3545
3659
</simplelist></para>
3546
3660
3661
<section id="dffi-callback-mem">
3662
<title>Callbacks and memory management</title>
3663
<para>Callbacks (&c-lang; function calling Lisp function) create
3664
so-called <firstterm>trampolines<indexterm id="dffi-trampoline">
3665
<primary>trampoline</primary></indexterm></firstterm>.
3666
A trampoline is a piece of &c-lang; code which knows how to call a
3667
particular Lisp function.
3668
(That is how all foreign language interfaces work, not just ours).
3669
The &c-lang; pointer that the foreign library receives is the pointer
3670
to this piece of code.
3671
These are ¬-e; subject to &gc;ion, as there is no protocol to
3672
tell the garbage collector when a given callback is not needed anymore
3673
(unlike with Lisp objects).</para>
3674
<para>With callbacks to <emphasis>named</emphasis> functions (i.e.,
3675
created by a &def-call-in; form where &func-r; is a &funname;) this is
3676
mostly harmless, since &func-r; is unlikely to be redefined.</para>
3677
<para>With callbacks to <emphasis>anonymous</emphasis> functions (i.e.,
3678
created by &foreign-function; or a &def-call-in; form where &func-r;
3679
argument is a &lambda-expr;), this might become an issue when they are
3680
produced dynamically and en masse, e.g. inside a loop, so that many
3681
trampolines are generated.</para>
3682
<para>You can use &foreign-free; to free the trampoline associated with a
3683
&foreign-function-t; object, but when you pass a &lambda-expr; to a
3684
&def-call-out; as an argument of type &c-function;, such a trampoline
3685
&is-e; allocated, but you do ¬-e; get hold of the associated trampoline
3686
object, and thus you cannot (trivially) free it.
3687
Thus you may find it easier to create the &foreign-function-t; object
3688
first, pass it to the &def-call-out;, and then call &foreign-free;
3689
manually.</para></section>
3690
3547
3691
</section>
3548
3692
3549
3693
<section id="allocation"><title>Argument and result passing conventions</title>
3632
3776
<emphasis role="platform">x86_64</emphasis> and &win32;)
3633
3777
have problems with this.
3634
3778
The recommended workaround is to pass pointers; this is fully supported.
3635
See also the &clisp-list; (<ulink role="sfmail" url="5513622"/>,
3636
<ulink role="gmane" url="devel/10089"/>).</simpara></warning>
3779
See also <ulink url="ml">clisp-devel</ulink>
3780
(<ulink role="sfmail" url="200307141526.26925.bruno%40clisp.org"/>/<ulink role="gmane" url="devel/10089"/>).</simpara></warning>
3637
3781
3638
3782
</section>
3639
3783
3653
3797
<varlistentry><term>&in-out-k; (means: read-write):</term>
3654
3798
<listitem><simpara>Information is passed from the caller to the callee
3655
3799
and then back to the caller. When viewed as a Lisp function, the
3656
&out-k; value is returned as an additional multiple value.
3800
&out-k; value is returned as an additional return value.
3657
3801
</simpara></listitem></varlistentry>
3658
3802
</variablelist>
3659
3803
3665
3809
3666
3810
<example id="dffi-simple"><title>Simple declarations and access</title>
3667
3811
3668
<para>The &c-lang; declaration
3669
3670
<programlisting language="C">
3812
<para>The &c-lang; declaration <programlisting language="C">
3671
3813
struct foo {
3672
int a;
3673
struct foo * b[100];
3814
int a;
3815
struct foo * b[100];
3674
3816
};
3675
</programlisting>
3676
3677
corresponds to
3678
3679
<programlisting language="lisp">
3680
(def-c-struct foo
3817
</programlisting> corresponds to <programlisting language="lisp">
3818
(&def-c-struct; foo
3681
3819
(a int)
3682
3820
(b (c-array (c-ptr foo) 100)))
3683
3821
</programlisting></para>
3684
3822
3685
<para>The element access
3686
3687
<programlisting language="C">
3823
<para>The element access <programlisting language="C">
3688
3824
struct foo f;
3689
3825
f.b[7].a
3690
</programlisting>
3691
3692
corresponds to
3693
3694
<programlisting language="lisp">
3826
</programlisting> corresponds to <programlisting language="lisp">
3695
3827
(declare (type foo f))
3696
(foo-a (aref (foo-b f) 7)) or (slot-value (aref (slot-value f 'b) 7) 'a)
3828
(foo-a (aref (foo-b f) 7)) <lineannotation>or</lineannotation>
3829
(slot-value (aref (slot-value f 'b) 7) 'a)
3697
3830
</programlisting></para></example>
3698
3831
3699
3832
<example id="dffi-extern-var">
3700
<title>external &c-lang; variable and some accesses</title>
3833
<title>External &c-lang; variable and some accesses</title>
3701
3834
3702
3835
<para><programlisting language="C">
3703
3836
struct bar {
3704
short x, y;
3705
char a, b;
3706
int z;
3707
struct bar * n;
3837
short x, y;
3838
char a, b;
3839
int z;
3840
struct bar * n;
3708
3841
};
3709
3842
3710
3843
extern struct bar * my_struct;
3712
3845
my_struct->x++;
3713
3846
my_struct->a = 5;
3714
3847
my_struct = my_struct->n;
3715
</programlisting>
3716
3717
corresponds to
3718
3719
<programlisting language="lisp">
3720
(def-c-struct bar
3848
</programlisting> corresponds to <programlisting language="lisp">
3849
(&def-c-struct; bar
3721
3850
(x short)
3722
3851
(y short)
3723
3852
(a char)
3724
(b char) ; or (b character) if it represents a character, not a number
3853
(b char) <lineannotation>or (b character) if it represents a character, not a number</lineannotation>
3725
3854
(z int)
3726
3855
(n (c-ptr bar)))
3727
3856
3728
(def-c-var my_struct (:type (c-ptr bar)))
3857
(&def-c-var; my_struct (:type (c-ptr bar)))
3729
3858
3730
(setq my_struct (let ((s my_struct)) (incf (slot-value s 'x)) s))
3731
or (incf (slot my_struct 'x))
3732
(setq my_struct (let ((s my_struct)) (setf (slot-value s 'a) 5) s))
3733
or (setf (slot my_struct 'a) 5)
3734
(setq my_struct (slot-value my_struct 'n))
3735
or (setq my_struct (deref (slot my_struct 'n)))
3859
(setq my_struct (let ((s my_struct)) (incf (slot-value s 'x)) s)) <lineannotation>or</lineannotation>
3860
(incf (slot my_struct 'x))
3861
(setq my_struct (let ((s my_struct)) (setf (slot-value s 'a) 5) s)) <lineannotation>or</lineannotation>
3862
(setf (slot my_struct 'a) 5)
3863
(setq my_struct (slot-value my_struct 'n)) <lineannotation>or</lineannotation>
3864
(setq my_struct (deref (slot my_struct 'n)))
3736
3865
</programlisting></para></example>
3737
3866
3738
3867
<example id="dffi-extern-func1"><title>Calling an external function</title>
3751
3880
This translates to
3752
3881
3753
3882
<programlisting language="lisp">
3754
(def-c-struct (div_t :typedef)
3883
(&def-c-struct; (div_t :typedef)
3755
3884
(quot int)
3756
3885
(rem int))
3757
(default-foreign-language :stdc)
3758
(def-call-out div (:arguments (numer int) (denom int))
3759
(:return-type div_t))
3886
(&default-foreign-language; :stdc)
3887
(&def-call-out; div (&arguments-k; (numer int) (denom int))
3888
(&ret-type-k; div_t))
3760
3889
</programlisting>
3761
3762
3890
Sample call from within Lisp (after running &clisp-link;):
3763
3764
3891
<programlisting language="lisp">
3765
3892
(div 20 3)
3766
3893
<computeroutput>#S(DIV_T :QUOT 6 :REM 2)</computeroutput>
3769
3896
<example id="dffi-extern-func2">
3770
3897
<title>Another example for calling an external function</title>
3771
3898
3772
<para>Suppose the following is defined in a file
3773
<filename>cfun.c</filename>:
3774
3899
<para>Suppose the following is defined in a file <filename>cfun.c</filename>:
3775
3900
<programlisting language="C">
3776
3901
struct cfunr { int x; char *s; };
3777
3902
struct cfunr * cfun (int i,char *s,struct cfunr * r,int a[10]) {
3798
3923
<programlisting language="lisp">
3799
3924
(&defpackage; "TEST-C-CALL" (:use &cl-pac; &ffi-pac;))
3800
3925
(&in-package; "TEST-C-CALL")
3801
(eval-when (compile) (setq &ffi-out-fun; t))
3802
(def-c-struct cfunr (x int) (s c-string))
3803
(default-foreign-language :stdc)
3804
(def-call-out cfun
3805
(:arguments (i int)
3806
(s c-string)
3807
(r (c-ptr cfunr) :in :alloca)
3808
(a (c-ptr (c-array int 10)) :in :alloca))
3809
(:return-type (c-ptr cfunr)))
3926
(&eval-when; (compile) (setq &ffi-out-fun; t))
3927
(&def-c-struct; cfunr (x int) (s c-string))
3928
(&default-foreign-language; :stdc)
3929
(&def-call-out; cfun (&ret-type-k; (c-ptr cfunr))
3930
(&arguments-k; (i int)
3931
(s c-string)
3932
(r (c-ptr cfunr) :in :alloca)
3933
(a (c-ptr (c-array int 10)) :in :alloca)))
3810
3934
(defun call-cfun ()
3811
3935
(cfun 5 "A Lisp string" (make-cfunr :x 10 :s "Another Lisp string")
3812
3936
'#(0 1 2 3 4 5 6 7 8 9)))
3815
3939
Use the &module; facility:
3816
3940
3817
3941
<screen>
3818
&sh-prompt; &clisp-link; create-module-set cfun callcfun.c
3942
&sh-prompt; &clisp-link; create cfun callcfun.c
3819
3943
&sh-prompt; cc -O -c cfun.c
3820
3944
&sh-prompt; cd cfun
3821
3945
&sh-prompt; ln -s ../cfun.o cfun.o
3822
3946
Add cfun.o to NEW_LIBS and NEW_FILES in &link-sh;.
3823
3947
&sh-prompt; cd ..
3824
3948
&sh-prompt; base/lisp.run -M base/lispinit.mem -c callcfun.lisp
3825
&sh-prompt; &clisp-link; add-module-set cfun base base+cfun
3949
&sh-prompt; &clisp-link; add base base+cfun cfun
3826
3950
&sh-prompt; base+cfun/lisp.run -M base+cfun/lispinit.mem -i callcfun
3827
3951
> (test-c-call::call-cfun)
3828
3952
i = 5
3841
3965
a[9] = 9.
3842
3966
#S(TEST-C-CALL::CFUNR :X 10 :S "A C string")
3843
3967
>
3844
&sh-prompt; rm -r base+cfun
3845
</screen></para>
3968
&sh-prompt; rm -r base+cfun</screen></para>
3846
3969
3847
3970
<para>Note that there is a memory leak here: The return value
3848
3971
<varname>r2</varname> of <function>cfun()</function> is
3849
3972
&malloc;ed but never &free;d. Specifying<programlisting language="lisp">
3850
(:return-type (c-ptr cfunr) :malloc-free)
3973
(&ret-type-k; (c-ptr cfunr) :malloc-free)
3851
3974
</programlisting>
3852
3975
is not an alternative because this would also
3853
3976
<function>free(r2->x)</function> but <varname>r2->x</varname> is a
3855
3978
3856
3979
<para>The memory leak can be avoided using
3857
3980
<programlisting language="lisp">
3858
(:return-type (c-pointer cfunr))
3981
(&ret-type-k; (c-pointer cfunr))
3859
3982
</programlisting>
3860
3983
instead, in conjunction with
3861
3984
<programlisting language="lisp">
3862
3985
(defun call-cfun ()
3863
3986
(let ((data (cfun ...)))
3864
(prog1 (&foreign-value; data)
3987
(&unwind-protect; (&foreign-value; data)
3865
3988
(&foreign-free; data :FULL nil))))
3866
3989
</programlisting></para></example>
3867
3990
3881
4004
int my_bar (int x) { return bar(x); }~%")
3882
4005
(&def-c-const; bar)
3883
4006
(&def-c-const; zot-size (:name "sizeof(struct zot)") (:guard nil))
3884
(&def-call-out; my-foo (:name "my_foo") (:arguments (x int)) (:return-type int))
3885
(&def-call-out; my-bar (:name "my_bar") (:arguments (x int)) (:return-type int))
4007
(&def-call-out; my-foo (:name "my_foo") (&arguments-k; (x ffi:int)) (&ret-type-k; ffi:int))
4008
(&def-call-out; my-bar (:name "my_bar") (&arguments-k; (x ffi:int)) (&ret-type-k; ffi:int))
3886
4009
</programlisting></para>
3887
4010
<para>Compiling this file will produce <filename>my.c</filename>
3888
4011
and <filename>my.fas</filename> and you have two options:
3889
4012
<orderedlist><listitem><para>Compile <filename>my.c</filename>
3890
into <filename>my.o</filename> with <screen>
3891
&sh-prompt; gcc -c my.c -lmylib
3892
</screen> and use &clisp-link; to create a new &clisp; &linkset;.
4013
into <filename>my.o</filename> with
4014
<screen>&sh-prompt; gcc -c my.c -lmylib</screen>
4015
and use &clisp-link; to create a new &clisp; &linkset;.
3893
4016
</para></listitem>
3894
<listitem><para>Add <code>(:library "my.dll")</code> to the
3895
&def-call-out; forms, compile <filename>my.c</filename>
3896
into <filename>my.so</filename> (or <filename>my.dll</filename> on
3897
&win32;) with <screen>
3898
&sh-prompt; gcc -shared -o my.so my.c -lmylib
3899
</screen> and load <filename>my.fas</filename>.
3900
</para></listitem></orderedlist></para>
4017
<listitem><para>Add <code>(&library-k; "my.dll")</code> to the &def-call-out;
4018
forms, compile <filename>my.c</filename> into <filename>my.so</filename>
4019
(or <filename>my.dll</filename> on &win32;) with
4020
<screen>&sh-prompt; gcc -shared -o my.so my.c -lmylib</screen> and
4021
load <filename>my.fas</filename>.</para></listitem></orderedlist></para>
3901
4022
<para>Of course, you could have created <filename>my1.c</filename>
3902
4023
containing<programlisting language="C">
3903
4024
#include <mylib.h>
3920
4041
extern void lispsort_begin (int);
3921
4042
void* lispsort_function;
3922
4043
void lispsort_double (int n, double * array) {
3923
double * sorted_array;
3924
int i;
3925
lispsort_begin(n); /* store #'sort2 in lispsort_function */
3926
sorted_array = ((double * (*) (double *)) lispsort_function) (array);
3927
for (i = 0; i < n; i++) array[i] = sorted_array[i];
3928
free(sorted_array);
4044
double * sorted_array;
4045
int i;
4046
lispsort_begin(n); /* store #'sort2 in lispsort_function */
4047
sorted_array = ((double * (*) (double *)) lispsort_function) (array);
4048
for (i = 0; i < n; i++) array[i] = sorted_array[i];
4049
free(sorted_array);
3929
4050
}
3930
4051
</programlisting>
3931
4052
3934
4055
<programlisting language="lisp">
3935
4056
(&defpackage; "FFI-TEST" (:use &cl-pac; &ffi-pac;))
3936
4057
(&in-package; "FFI-TEST")
3937
(eval-when (compile) (setq &ffi-out-fun; t))
3938
(def-call-in lispsort_begin (:arguments (n int))
3939
(:return-type nil)
3940
(:language :stdc))
3941
(def-c-var lispsort_function (:type c-pointer))
4058
(&eval-when; (compile) (setq &ffi-out-fun; t))
4059
(&def-call-in; lispsort_begin (&arguments-k; (n int))
4060
(&ret-type-k; nil)
4061
(&lang-k; :stdc))
4062
(&def-c-var; lispsort_function (:type c-pointer))
3942
4063
(defun lispsort_begin (n)
3943
4064
(setf (cast lispsort_function
3944
4065
`(c-function
3945
(:arguments (v (c-ptr (c-array double-float ,n))))
3946
(:return-type (c-ptr (c-array double-float ,n))
4066
(&arguments-k; (v (c-ptr (c-array double-float ,n))))
4067
(&ret-type-k; (c-ptr (c-array double-float ,n))
3947
4068
:malloc-free)))
3948
4069
#'sort2))
3949
4070
(defun sort2 (v)
3954
4075
To test this, use the following test file <filename>sorttest.lisp</filename>:
3955
4076
3956
4077
<programlisting language="lisp">
3957
(eval-when (compile) (setq &ffi-out-fun; t))
3958
(def-call-out sort10
4078
(&eval-when; (compile) (setq &ffi-out-fun; t))
4079
(&def-call-out; sort10
3959
4080
(:name "lispsort_double")
3960
(:language :stdc)
3961
(:arguments (n int)
4081
(&lang-k; :stdc)
4082
(&arguments-k; (n int)
3962
4083
(array (c-ptr (c-array double-float 10)) :in-out)))
3963
4084
</programlisting>
3964
4085
3965
4086
Now try
3966
4087
3967
<screen>
3968
&sh-prompt; &clisp-link; create-module-set sort sort2.c sorttest.c
4088
<screen>&sh-prompt; &clisp-link; create sort sort2.c sorttest.c
3969
4089
&sh-prompt; cc -O -c sort1.c
3970
4090
&sh-prompt; cd sort
3971
&sh-prompt; ln -s ../sort1.o sort1.o
3972
</screen>
4091
&sh-prompt; ln -s ../sort1.o sort1.o</screen>
3973
4092
3974
4093
Add <filename>sort1.o</filename> to <envar>NEW_LIBS</envar>
3975
4094
and <envar>NEW_FILES</envar> in &link-sh;.
3979
4098
and add <filename>package.lisp</filename> to &mod-preload; in &link-sh;.
3980
4099
Proceed:
3981
4100
3982
<screen>
3983
&sh-prompt; cd ..
4101
<screen>&sh-prompt; cd ..
3984
4102
&sh-prompt; base/lisp.run -M base/lispinit.mem -c sort2.lisp sorttest.lisp
3985
&sh-prompt; &clisp-link; add-module-set sort base base+sort
4103
&sh-prompt; &clisp-link; add base base+sort sort
3986
4104
&sh-prompt; base+sort/lisp.run -M base+sort/lispinit.mem -i sort2 sorttest
3987
4105
> (sort10 10 '#(0.501d0 0.528d0 0.615d0 0.550d0 0.711d0
3988
4106
0.523d0 0.585d0 0.670d0 0.271d0 0.063d0))
3989
4107
#(0.063d0 0.271d0 0.501d0 0.523d0 0.528d0 0.55d0 0.585d0 0.615d0 0.67d0 0.711d0)
3990
&sh-prompt; rm -r base+sort
3991
</screen></para></example>
4108
&sh-prompt; rm -r base+sort</screen></para></example>
3992
4109
3993
4110
<example id="ex-call-in-dll">
3994
4111
<title>Calling Lisp from &c-lang; dynamically</title>
4006
4123
<programlisting language="lisp">
4007
4124
(ffi:def-call-out callout
4008
4125
(:name "CallInFunc")
4009
(:library "lispdll.dll")
4010
(:arguments (function-arg
4011
(ffi:c-function (:arguments (number ffi:int))
4012
(:return-type ffi:int) (:language :stdc))))
4013
(:return-type ffi:int)
4014
(:language :stdc))
4126
(&library-k; "lispdll.dll")
4127
(&arguments-k; (function-arg
4128
(ffi:c-function (&arguments-k; (number ffi:int))
4129
(&ret-type-k; ffi:int) (&lang-k; :stdc))))
4130
(&ret-type-k; ffi:int)
4131
(&lang-k; :stdc))
4015
4132
(defun f (x) (* x 2))
4016
4133
<computeroutput>F</computeroutput>
4017
4134
(callout #'f)
4021
4138
<example id="dffi-gethostname"><title>Variable size arguments:
4022
4139
calling <function role="unix">gethostname</function> from &clisp;</title>
4023
4140
4024
<para><funcsynopsis id="gethostname-synopsis"><funcprototype>
4141
<para>The standard &unix; function
4142
<funcsynopsis id="gethostname-synopsis"><funcprototype>
4025
4143
<funcdef><type>int</type> <function>gethostname</function></funcdef>
4026
4144
<paramdef><type>char*</type> <parameter>name</parameter></paramdef>
4027
<paramdef><type>size_t</type> <parameter>namelen</parameter></paramdef>
4145
<paramdef><type>size_t</type> <parameter>length</parameter></paramdef>
4028
4146
</funcprototype></funcsynopsis>
4029
follows a typical pattern of &c-lang; "out"-parameter convention - it
4030
expects a pointer to a buffer it is going to fill.
4147
follows a typical pattern of &c-lang; <quote>out</quote>-parameter
4148
convention: it expects a pointer to a buffer it is going to fill.
4031
4149
So you must view this parameter as either &out-k; or &in-out-k;.
4032
4150
Additionally, one must tell the function the size of the buffer.
4033
Here <replaceable>namelen</replaceable> is just an &in-k; parameter.
4151
Here &len-r; is just an &in-k; parameter.
4034
4152
Sometimes this will be an &in-out-k; parameter, returning the
4035
4153
number of bytes actually filled in.</para>
4036
4154
4037
<para>So &name-r; is actually a pointer to an array of up to
4038
<replaceable>namelen</replaceable> characters, regardless of what the
4039
poor <type>char*</type> &c-lang; prototype says, to be used like a
4040
&c-lang; <type>string</type> (&c-NULL;-termination). &unix; specifies
4041
that <quote>host names are limited to
4042
<constant>HOST_NAME_MAX</constant> bytes</quote>, which is, of course,
4043
system dependent, but it appears that 256 is sufficient.</para>
4155
<para>So &name-r; is actually a pointer to an array of up to &len-r;
4156
characters, regardless of what the poor <type>char*</type> &c-lang;
4157
prototype says, to be used like a &c-lang; <type>string</type>
4158
(&c-NULL;-termination). &unix; specifies that <quote>host names are
4159
limited to <constant>HOST_NAME_MAX</constant> bytes</quote>, which is,
4160
of course, system dependent, but it appears that 256 is sufficient.</para>
4044
4161
4045
4162
<para>In the present example, you can use allocation &alloca-k;, like
4046
you would do in &c-lang;: stack-allocate a temporary.</para>
4047
4163
you would do in &c-lang;: stack-allocate a temporary:
4048
4164
<programlisting language="lisp">
4049
4165
(&def-call-out; gethostname
4050
(:arguments (name (&c-ptr; (&c-array-max; ffi:char 256))
4166
(&arguments-k; (name (&c-ptr; (&c-array-max; ffi:char 256))
4051
4167
&out-k; &alloca-k;)
4052
(len ffi:int))
4053
(:language :stdc)
4054
(:return-type ffi:int))
4055
4168
(length ffi:int))
4169
(&lang-k; :stdc) (&library-k; :default)
4170
(&ret-type-k; ffi:int))
4171
<computeroutput>GETHOSTNAME</computeroutput>
4056
4172
(defun myhostname ()
4057
(multiple-value-bind (success name)
4058
;; &out-k; and &in-out-k; parameters are returned as &mul-val;
4173
(multiple-value-bind (success name)<lineannotation>&out-k; and &in-out-k; parameters are returned as &mul-val;</lineannotation>
4059
4174
(gethostname 256)
4060
4175
(if (zerop success) name
4061
(error ...)))) ;; <function role="unix">strerror</function>(<varname role="unix">errno</varname>)
4062
4063
(defvar hostname (myhostname))
4064
</programlisting>
4065
</example>
4176
(error "~S: ~S: ~S" 'myhostname (os:errno) (os:strerror)))))<lineannotation>See <xref linkend="errno"/></lineannotation>
4177
<computeroutput>MYHOSTNAME</computeroutput>
4178
(myhostname)
4179
<computeroutput>#(97 98 97 122 111 110 107)</computeroutput></programlisting>
4180
It is a &simple-vector-t;, not a &string-t;, because the &name-r;
4181
argument is an array of <type>char</type> (an &integer-t; type, see
4182
<xref linkend="dffi-types"/>), not <type>character</type>.
4183
<programlisting language="lisp">
4184
(&def-call-out; gethostname
4185
(&arguments-k; (name (&c-ptr; (&c-array-max; character 256))
4186
&out-k; &alloca-k;)
4187
(length ffi:int))
4188
(&lang-k; :stdc) (&library-k; :default)
4189
(&ret-type-k; ffi:int))
4190
<computeroutput>GETHOSTNAME</computeroutput>
4191
(myhostname)
4192
<computeroutput>"abazonk"</computeroutput></programlisting>
4193
Now we have a different problem:
4194
if <function role="unix">gethostname</function> fails, then the buffer
4195
allocated for &name-r; will be filled with garbage, but it will still go
4196
through the string conversion &before-e; we can check
4197
the <replaceable>success</replaceable> status.
4198
If &foreign-enc; is &iso-8859-1;, this is not a problem since no real
4199
conversion is happening, but with &utf-8; an &error-t; may be &signal;ed.
4200
A safe approach is to pass to the foreign function our own
4201
stack-allocated buffer, and only convert the buffer to a string when the
4202
foreign function succeeds: <programlisting language="lisp">
4203
(&def-call-out; gethostname
4204
(&arguments-k; (name &c-pointer;)
4205
(length ffi:int))
4206
(&lang-k; :stdc) (&library-k; :default)
4207
(&ret-type-k; ffi:int))
4208
<computeroutput>GETHOSTNAME</computeroutput>
4209
(defun myhostname ()
4210
(&with-foreign-object; (name '(&c-array-max; character 256))
4211
(let ((success (gethostname name 256)))
4212
(if (zerop success) (&foreign-value; name)
4213
(error "~S: ~S: ~S" 'myhostname (os:errno) (os:strerror))))))
4214
<computeroutput>MYHOSTNAME</computeroutput>
4215
(myhostname)
4216
<computeroutput>"abazonk"</computeroutput></programlisting>
4217
Note that the &type-r; argument of &with-foreign-object; is evaluated,
4218
so we do not have to make any assumptions
4219
about <constant>HOST_NAME_MAX</constant>: <programlisting language="lisp">
4220
(defun myhostname ()
4221
(let ((host-name-max (<link linkend="sysinfo">os:sysconf</link> :host-name-max)))
4222
(&with-foreign-object; (name `(&c-array-max; character ,host-name-max))
4223
(let ((success (gethostname name host-name-max)))
4224
(if (zerop success) (&foreign-value; name)
4225
(error "~S: ~S: ~S" 'myhostname (os:errno) (os:strerror)))))))
4226
<computeroutput>MYHOSTNAME</computeroutput>
4227
(myhostname)
4228
<computeroutput>"abazonk"</computeroutput></programlisting>
4229
</para></example>
4066
4230
4067
4231
<example id="dffi-dll-var">
4068
4232
<title>Accessing variables in shared libraries</title>
4096
4260
(out double-float))
4097
4261
4098
4262
(&def-call-out; get-own-c-float
4099
(:library "libtest.so")
4100
(:language :stdc)
4263
(&library-k; "libtest.so")
4264
(&lang-k; :stdc)
4101
4265
(:name "test_dll")
4102
(:arguments (ptr c-pointer :in :alloca))
4103
(:return-type double-float))
4266
(&arguments-k; (ptr c-pointer :in :alloca))
4267
(&ret-type-k; double-float))
4104
4268
4105
4269
(&def-c-var; my-c-var (:name "my_struct")
4106
(:library "libtest.so") (:type (c-ptr bar)))
4270
(&library-k; "libtest.so") (:type (c-ptr bar)))
4107
4271
</programlisting></para>
4108
4272
4109
4273
<para>Note that <function>get-own-c-float</function> takes a
4135
4299
All pointers depending on this resource can be disabled at once upon
4136
4300
close by sharing their &foreign-pointer; using &set-foreign-pointer;.
4137
4301
<programlisting language="lisp">
4138
(def-c-type PGconn c-pointer) ; opaque pointer
4139
(def-call-out PQconnectdb (:return-type PGconn)
4140
(:arguments (conninfo c-string)))
4302
(&def-c-type; PGconn c-pointer)<lineannotation>opaque pointer</lineannotation>
4303
(&def-call-out; PQconnectdb (&ret-type-k; PGconn)
4304
(&arguments-k; (conninfo c-string)))
4141
4305
(defun sql-connect (conninfo)
4142
4306
(let ((conn (PQconnectdb conninfo)))
4143
4307
(unless conn (error "NULL pointer"))
4144
4308
;; may wish to use &finalize; as well
4145
4309
(&set-foreign-pointer; conn ©-k;)))
4146
4310
(defun sql-dependent-resource (conn arg1)
4147
(let ((res (PQxxx conn arg1)))
4148
(&set-foreign-pointer; res conn)))
4311
(&set-foreign-pointer; (PQxxx conn arg1) conn))
4149
4312
(defun sql-close (connection)
4150
4313
(when (&validp; connection)
4151
4314
(PQfinish connection)
4156
4319
the dependent resource will invalidate the primary one.</para></warning>
4157
4320
<note><para>An alternative approach to resource management,
4158
4321
more suitable to non-&ffi-pac; &module;s,
4159
is implemented in the <link linkend="berkeley-db">berkeley-db</link>
4160
module, see <xref linkend="bdb-close"/>.</para></note></para></example>
4322
is implemented in the &berkeley-db-mod; module,
4323
see <xref linkend="bdb-close"/>.</para></note></para></example>
4161
4324
4162
<example id="ex-dffi-float"><title>Float point array computations</title>
4325
<example id="ex-dffi-float"><title>Floating point arrays</title>
4163
4326
<para>Save this code into <filename>sum.c</filename>:
4164
4327
<programlisting language="C">
4165
4328
double sum (int len, double *vec) {
4173
4336
<screen>&sh-prompt; gcc -shared -o libsum.so sum.c</screen>
4174
4337
Now you can sum doubles:
4175
4338
<programlisting language="lisp">
4176
(&def-call-out; sum (:name "sum") (:library "libsum.so") (:language :stdc)
4177
(:return-type double-float)
4178
(:arguments (len int) (vec (&c-array-ptr; double-float))))
4339
(&def-call-out; sum (:name "sum") (&library-k; "libsum.so") (&lang-k; :stdc)
4340
(&ret-type-k; ffi:double-float)
4341
(&arguments-k; (len ffi:int) (vec (&c-array-ptr; ffi:double-float))))
4179
4342
(sum 3 #(1d0 2d0 3d0))
4180
4343
<computeroutput>6d0</computeroutput>
4181
</programlisting>
4182
</para>
4183
</example>
4344
</programlisting></para></example>
4184
4345
4185
4346
<section id="dffi-ex-more"><title>More examples</title>
4186
4347
4187
4348
<para>You can find more information and examples of the &clisp;
4188
&ffi-pac; in the following &clisp-list; messages:
4349
&ffi-pac; in the following <ulink url="ml">clisp-list</ulink> messages:
4189
4350
<variablelist><varlistentry><term>variable size values</term>
4190
<listitem><simpara><ulink role="sfmail" url="5736140"/>,
4191
<ulink role="gmane" url="general/7278"/></simpara></listitem></varlistentry>
4351
<listitem><simpara><ulink role="sfmail" url="9F8582E37B2EE5498E76392AEDDCD3FE05F4B8F7%40G8PQD.blf01.telekom.de"/>/<ulink role="gmane" url="general/7278"/>
4352
</simpara></listitem></varlistentry>
4192
4353
<varlistentry><term>variable length arrays</term>
4193
<listitem><simpara><ulink role="sfmail" url="4062459"/>,
4194
<ulink role="gmane" url="general/6626"/></simpara></listitem>
4195
</varlistentry></variablelist></para>
4354
<listitem><simpara><ulink role="sfmail" url="9F8582E37B2EE5498E76392AEDDCD3FE0287A252%40G8PQD.blf01.telekom.de"/>/<ulink role="gmane" url="general/6626"/>
4355
<ulink role="sfmail" url="9F8582E37B2EE5498E76392AEDDCD3FE0287A3B1%40G8PQD.blf01.telekom.de"/>/<ulink role="gmane" url="general/6628"/>
4356
</simpara></listitem></varlistentry></variablelist></para>
4196
4357
<para>Even more examples can be found in the file
4197
4358
<filename role="clisp-cvs">tests/ffi.tst</filename>
4198
4359
in the &clisp; source distribution.</para>
4208
4369
4209
4370
<section id="socket-intro"><title>Introduction</title>
4210
4371
4211
<para>Sockets are used for interprocess communications by processes
4212
running on the same host as well as by processes running on different
4213
hosts over a computer network.
4372
<para><ulink url="http://www.freesoft.org/CIE/Topics/20.htm">Sockets</ulink>
4373
are used for interprocess communications by processes running on the
4374
same host as well as by processes running on different hosts over a
4375
computer network.
4214
4376
The most common kind of sockets is Internet stream sockets, and a
4215
4377
high-level interface to them is described here.
4216
4378
A more low level interface that closely follows the &c-lang; system
4217
4379
calls is also available, see <xref linkend="rawsock"/>.</para>
4218
4380
4219
4381
<para>Two main varieties of sockets are interfaced to:
4220
<itemizedlist><listitem><simpara><quote>active</quote> sockets
4221
correspond to &socket-stream;s which are &bidir-s; &stream-t;s
4222
</simpara></listitem>
4223
<listitem><simpara><quote>passive</quote> sockets correspond to
4224
&socket-server;s which are a special kind of objects that are used
4225
to allow the other side to initiate interaction with lisp.
4226
</simpara></listitem></itemizedlist></para>
4382
<variablelist><varlistentry><term><quote>active</quote> sockets</term>
4383
<listitem><simpara>correspond to &socket-stream;s which are &bidir-s;
4384
&stream-t;s</simpara></listitem></varlistentry>
4385
<varlistentry><term><quote>passive</quote> sockets</term>
4386
<listitem><simpara>correspond to &socket-server;s which are a special
4387
kind of objects that are used to allow the other side to initiate
4388
interaction with lisp.</simpara></listitem></varlistentry>
4389
</variablelist></para>
4227
4390
4228
4391
<example id="socket-ex-server"><title>Lisp &repl; server</title>
4229
4392
<para>Here is a simple lisp &repl; server that waits for a remote
4233
4396
(&format; t "~&Waiting for a connection on ~S:~D~%"
4234
4397
(&sose-host; server) (&sose-port; server))
4235
4398
(&unwind-protect;
4236
;; infinite loop, terminate with <keycombo>&ctrl;<keysym>C</keysym></keycombo>
4399
;; infinite loop, terminate with &ctrl-c;
4237
4400
(&loop; (&with-open-stream; (socket (&so-accept; server))
4238
4401
(&multiple-value-bind; (local-host local-port) (&sost-local; socket)
4239
4402
(&multiple-value-bind; (remote-host remote-port) (&sost-peer; socket)
4240
4403
(&format; &t; "~&Connection: ~S:~D -- ~S:~D~%"
4241
4404
remote-host remote-port local-host local-port)))
4242
;; loop is terminated when the remote host closes the connection or on <link linkend="quit"><function>EXT:EXIT</function></link>
4405
;; loop is terminated when the remote host closes the connection or on &exit;
4243
4406
(&loop; (&when; (&eq; :eof (&so-status; (cons socket :input))) (&return;))
4244
4407
(&print; (&eval; (&read; socket)) socket)
4245
4408
;; flush everything left in socket
4253
4416
remote host to execute arbitrary code with your permissions.
4254
4417
While functions defined in lisp (like &run-cmd;) can be removed
4255
4418
(using &fmakunbound;), the built-in functions (like &shell; and &exec;)
4256
cannot be permanently removed from the run-time, and an experienced
4419
cannot be permanently removed from the &rt;, and an experienced
4257
4420
hacker will be able to invoke them even if you &fmakunbound; their names.
4258
</simpara><simpara>You should limit the socket server to local
4259
connections by passing string <literal role="data">"127.0.0.1"</literal>
4260
as the <constant>:INTERFACE</constant> argument.</simpara></warning></para>
4261
</example>
4421
</simpara><simpara>You should limit the socket server to local connections
4422
by passing the &string-t; <literal role="data">"127.0.0.1"</literal>
4423
as the <constant>:INTERFACE</constant> argument to &sose;.</simpara></warning>
4424
</para></example>
4262
4425
4263
4426
<example id="socket-ex-client"><title>Lisp &http; client</title>
4264
4427
<para>Here are a couple of simple lisp &http; clients that fetch a web
4448
4611
return, then the second value is positive (this is the reason &nil;
4449
4612
is ¬-e; treated as an empty &list-t;, but as an invalid
4450
4613
argument).</simpara>
4614
<simpara>Note that &so-status; may &signal; a &stream-error-t;.
4615
This happens if the &socket-stream; receives an <code>RST</code> packet,
4616
see <filename role="clisp-cvs">tests/econnreset.lisp</filename>.</simpara>
4451
4617
<simpara>This is the interface to <function role="unix">select</function>
4452
4618
(on some platforms, <function role="unix">poll</function>),
4453
4619
so it will work on any &clisp; &stream-t; which is based on a
4500
4666
<varlistentry id="so-opt"><term><code>(&so-opt; &sose-r; &rest-amp;
4501
4667
{&option-r;}*)</code></term>
4502
4668
<listitem><simpara>Query and, optionally, set socket options using
4503
<function role="unix">getsockopt</function>
4504
and <function role="unix">setsockopt</function>.
4669
<function role="unix">getsockopt</function> and &setsockopt;.
4505
4670
An &option-r; is a keyword, optionally followed by the new value.
4506
When the new value is not supplied,
4507
<function role="unix">setsockopt</function> is not called.
4671
When the new value is not supplied, &setsockopt; is not called.
4508
4672
For each option the old (or current, if new value was not supplied)
4509
4673
value is returned. E.g., <code>(&so-opt; &sose-r;
4510
4674
:SO-LINGER 1 :SO-RCVLOWAT)</code> returns 2 values: &nil;, the old
4520
4684
<!-- #endif -->
4521
4685
</section>
4522
4686
4687
<section id="mt"><title>Multiple Threads of Execution</title>
4688
<subtitle><emphasis role="plat-dep">Only in &clisp; built &with;
4689
compile-time flag <option>--with-threads</option>.</emphasis></subtitle>
4690
4691
<warning><simpara>This functionality is
4692
<emphasis role="strong">experimental</emphasis>.</simpara>
4693
<simpara>Use it at your own risk.</simpara>
4694
<simpara>Discuss it on <ulink url="ml">clisp-devel</ulink>.</simpara></warning>
4695
4696
<section id="mt-intro"><title>Introduction</title>
4697
<para>&clisp; uses the OS threads to implement multiple threads of execution.
4698
Two flavors are supported: &posix; and &win32;. Both are preemptive.</para>
4699
<para>All symbols are exported from the package &mt-pac;, which has nicknames
4700
<quote role="package">MT</quote> (for <emphasis>MultiThreading</emphasis>) and
4701
<quote role="package">MP</quote> (for <emphasis>MultiProcessing</emphasis>).
4702
When this functionality is present, &features-my;
4703
contains the symbol <constant>:MT</constant>.</para>
4704
<para>See also <xref linkend="gc-mt"/>.</para></section>
4705
4706
<section id="mt-general"><title>General principles</title>
4707
4708
<section id="mt-parallelizability"><title>Parallelizability</title>
4709
4710
<para>A program developed for a single-threaded world which shares no
4711
application objects with programs running in other threads must run
4712
fine, without problems.</para>
4713
4714
<para>Specfically:
4715
if, in a single-threaded world, execution of program A before program B
4716
produces semantically the same results as execution of program B before
4717
program A, then in a multithreaded world, it is possible to run A and B
4718
simultaneously in different threads, and the result will be the same as
4719
in the two single-threaded cases (A before B, or B before A).
4720
<itemizedlist><title>Summary</title>
4721
<listitem><simpara>If A and B have no common objects, then the
4722
implementation ensures that the principle is fulfilled.</simpara></listitem>
4723
<listitem><simpara>If A and B share some objects, the implementation
4724
allows the programs to satisfy the principle with little effort.
4725
</simpara></listitem></itemizedlist></para></section>
4726
4727
<section id="mt-symvalue"><title>Special Variable Values</title>
4728
<para>Every &dyn-var; has a global value that can be shared across all
4729
&thread;s.</para>
4730
<para>Bindings of &dyn-var;s (via &let;/&let-star;/&multiple-value-bind;)
4731
are local to &thread;s, i.e. every &symbol-t; has a different value cell in
4732
each &thread;. &symbol-value-thread; can be used to inspect and modify
4733
these thread local bindings.</para>
4734
<para>Threads do not inherit dynamic bindings from the parent thread.</para>
4735
4736
<para>Example:<programlisting language="lisp">
4737
(defvar *global* 1)<lineannotation>create a &glob-var;</lineannotation>
4738
(defun thread-1 ()
4739
<lineannotation>here *global* and (&symbol-value; *global*) will be 1 not 2!</lineannotation>
4740
(setq *global* 5)<lineannotation>change the &glob-var; value</lineannotation>
4741
(let ((*global* 10))<lineannotation>&thr-var; value is initialized</lineannotation>
4742
(setq *global* 20)<lineannotation>&thr-var; value is changed</lineannotation>
4743
<lineannotation>&glob-var; value is not accessible here (only via &symbol-value-thread;)</lineannotation>
4744
)
4745
(setq *global* 30))<lineannotation>&glob-var; value is modified again</lineannotation>
4746
(let ((*global* 2))<lineannotation>&thr-var; value is initialized</lineannotation>
4747
(&make-thread; #'thread-1))
4748
</programlisting></para>
4749
4750
</section>
4751
4752
<section id="mt-package"><title>Packages</title>
4753
<subtitle>This information is likely to change in the near future</subtitle>
4754
<para>&package-t; objects have an internal mutex and are locked by
4755
&intern; before adding a symbol (if &find-symbol; fails). All
4756
modifications of internal package data are guarded by this mutex.</para>
4757
<warning><para>Currently there is one exception: &use-package; is not
4758
protected and thus not thread safe.</para></warning>
4759
<warning><para>Symbol look-up within package currently is not guarded!
4760
This means that in certain cases &find-symbol; may return &nil; even
4761
though the symbol is accessible (this may happen when internal package
4762
hash tables are re-hashed at the time &find-symbol; performs look-up).
4763
</para></warning>
4764
<para>One crucial implication is that one <emphasis>cannot</emphasis>
4765
call &load; from different threads at the same time.</para>
4766
<para>See also <xref linkend="mt-clos"/>.</para></section>
4767
4768
<section id="mt-clos"><title>&clos;</title>
4769
<subtitle>This information is likely to change in the near future</subtitle>
4770
<para>&clos; is ¬-e; thread-safe. &defclass;, &defgeneric;,
4771
&defmethod;, &defstruct; modify &clos; without any locking and may
4772
interfere with each other.</para>
4773
<para>It is recommended that all code is &load;ed &before-e;
4774
any &thread;s are spawned.</para>
4775
<para>See also <xref linkend="mt-package"/>.</para></section>
4776
4777
<section id="mt-mutable"><title>Hash Tables, Sequences, and other
4778
mutable objects</title>
4779
<subtitle>If you want to shoot yourself, it is <emphasis>your</emphasis>
4780
responsibility to wear armor.</subtitle>
4781
4782
<para>Nothing is ever locked automatically (automatic locking will
4783
impose an unjustifiable penalty on &hash-table-t;s and &sequence-t;s
4784
local to threads), so the user must use locks when sharing
4785
&hash-table-t;s, &sequence-t;s and user-defined mutable objects between
4786
threads.</para>
4787
<para>This approach is consistent with the usual &cl; approach:
4788
<blockquote><attribution><ulink role="clhs" url="sec_3-6"/></attribution>
4789
<para>The consequences are undefined when code executed during an
4790
object-traversing operation destructively modifies the object in a
4791
way that might affect the ongoing traversal operation...
4792
</para></blockquote>
4793
<blockquote><attribution><ulink role="clhs" url="sec_18-1-2"/></attribution>
4794
<para>If an object O1 is used as a key in a hash table H and is then
4795
visibly modified with regard to the equivalence test of H, then the
4796
consequences are unspecified if O1 is used as a key in further
4797
operations on H...</para></blockquote></para>
4798
</section>
4799
4800
<section id="mt-unsafe"><title>Examples of thread-unsafe code</title>
4801
<para>Here are some forms whose results are undefined if two threads
4802
evaluate them without locking:<programlisting language="lisp">
4803
(&incf; (&gethash; x global-ht 0))<lineannotation>see <xref linkend="mt-mutable"/></lineannotation>
4804
(&setf; (&aref; global-array ...) ...)<lineannotation>ditto</lineannotation>
4805
(&defmethod; &gf-r; (...) ...)<lineannotation>see <xref linkend="mt-clos"/></lineannotation>
4806
(&load; &filename-r;)<lineannotation>see <xref linkend="mt-package"/></lineannotation>
4807
(&read-from-string; &string-r;)<lineannotation>ditto</lineannotation>
4808
</programlisting></para></section>
4809
4810
</section>
4811
4812
<section id="mt-api"><title>Thread API reference</title>
4813
<variablelist>
4814
<varlistentry id="thread"><term>&thread;</term>
4815
<listitem><simpara>The type of the object returned by &make-thread;.</simpara>
4816
<simpara>Each &thread; represent a separate computation, executed in
4817
parallel to each other.</simpara></listitem></varlistentry>
4818
<varlistentry id="make-thread"><term><code>(&make-thread; &func-r;
4819
&key-amp; &name-k; :INITIAL-BINDINGS :CSTACK-SIZE :VSTACK-SIZE)</code></term>
4820
<listitem><simpara>Start a new named &thread; running &func-r;.</simpara>
4821
<variablelist>
4822
<varlistentry><term><constant>:INITIAL-BINDINGS</constant></term>
4823
<listitem><simpara>an &alist; of <literal role="data">(&symbol-r;
4824
. &form-r;)</literal>.
4825
The &form-r;s are &eval;uated in the context of the new thread
4826
and &symbol-r;s are bound to the result in the thread before &func-r; is
4827
called. The default value is &default-special-bindings;.
4828
</simpara></listitem></varlistentry>
4829
<varlistentry><term><constant>:CSTACK-SIZE</constant></term>
4830
<listitem><simpara>the size in bytes of the control (&c-lang;) stack.
4831
If 0, the value is decided by the OS.</simpara></listitem></varlistentry>
4832
<varlistentry><term><constant>:VSTACK-SIZE</constant></term>
4833
<listitem><simpara>the size of the &clisp; &STACK; in &object-t;s.
4834
The default value is calculated based on the &opt-m; option
4835
used when &clisp; was started.
4836
If 0, the value will be the same as that of the calling thread.
4837
</simpara></listitem></varlistentry></variablelist>
4838
<simpara>If &thread; creation fails (e.g., due to a lack of system
4839
memory), a &control-error-t; is &signal;ed.</simpara>
4840
<simpara>Cf. <function role="unix">pthread_create</function>.</simpara>
4841
</listitem></varlistentry>
4842
<varlistentry id="threadp"><term><code>(&threadp; &object-r;)</code></term>
4843
<listitem><simpara>Check whether the object is of type &thread;.
4844
</simpara></listitem></varlistentry>
4845
<varlistentry id="thread-yield"><term><code>(&thread-yield; &thr;)</code></term>
4846
<listitem><simpara>Relinquish the CPU. The &thr; is placed at the end
4847
of the run queue and another thread is scheduled to run.</simpara>
4848
<simpara>Cf. <function role="unix">sched_yield</function>.</simpara>
4849
</listitem></varlistentry>
4850
<varlistentry id="thread-interrupt"><term><code>(&thread-interrupt; &thr;
4851
&key-amp; &function-k; &override-k; &arguments-k;)</code></term>
4852
<listitem><simpara>Interrupt the normal execution flow in &thr; and ask
4853
it to &apply; &func-r; to &args-r;.</simpara>
4854
<simpara>Use <code>(&thread-interrupt; &thr; &function-k; &nil;)</code>
4855
to debug &thr; and <code>(&thread-interrupt; &thr; &function-k;
4856
&t;)</code> to terminate &thr;.</simpara>
4857
<simpara>The &override-k; argument overrides &with-deferred-interrupts;
4858
and should be used with extreme care.</simpara>
4859
<simpara>Threads can only be interrupted at a point where the &gc;ion
4860
can run, see <xref linkend="gc-mt"/>.</simpara>
4861
<simpara>Currently on &win32; blocking I/O cannot be interrupted.
4862
The interrupt will be handled after the call returns.</simpara>
4863
<warning><para>Thread may be interrupted inside &unwind-protect;'s
4864
cleanup forms and on non-local exit from &func-r; -
4865
they may not execute entirely. In order to prevent this,
4866
&with-deferred-interrupts; is provided.</para></warning>
4867
</listitem></varlistentry>
4868
<varlistentry id="thread-name"><term><code>(&thread-name; &thr;)</code></term>
4869
<listitem><simpara>Return the &name-r; of the &thr;.
4870
</simpara></listitem></varlistentry>
4871
<varlistentry id="thread-active-p"><term><code>(&thread-active-p;
4872
&thr;)</code></term>
4873
<listitem><simpara>Return &nil; if the thread has already terminated
4874
and &t; otherwise.</simpara>
4875
<warning><para>By the time this function returns &t;, &thr; may have
4876
already terminated anyway.</para></warning></listitem></varlistentry>
4877
<varlistentry id="current-thread"><term><code>(¤t-thread;)</code></term>
4878
<listitem><simpara>Return the &thread; object encapsulating the caller.
4879
</simpara></listitem></varlistentry>
4880
<varlistentry id="list-threads"><term><code>(&list-threads;)</code></term>
4881
<listitem><simpara>Return the &list-t; of all currently running &thread;s.
4882
</simpara><warning><para>By the time this function returns, the set of
4883
actually running threads may have a single intersection with the
4884
return value - the ¤t-thread;.
4885
</para></warning></listitem></varlistentry>
4886
<varlistentry id="mutex"><term>&mutex;</term>
4887
<listitem><simpara>The type of the object return by &make-mutex;.</simpara>
4888
<simpara>This represents a <emphasis>lock</emphasis>, i.e., a way to
4889
prevent different threads from doing something at the same time,
4890
e.g., modifying the same object.</simpara></listitem></varlistentry>
4891
<varlistentry id="mutexp"><term><code>(&mutexp; &object-r;)</code></term>
4892
<listitem><simpara>Check whether the object is of type &mutex;.
4893
</simpara></listitem></varlistentry>
4894
<varlistentry id="make-mutex"><term><code>(&make-mutex; &key-amp;
4895
&name-k; <constant>:RECURSIVE-P</constant>)</code></term>
4896
<listitem><simpara>Create new &mutex; object - not locked by any thread.
4897
&name-k; should be a &string-t; describing the mutex (this really helps
4898
debugging deadlocks). When <replaceable>RECURSIVE-P</replaceable> is
4899
non-&nil;, a recursive &mutex; is created i.e., a thread can acquire
4900
the mutex repeatedly (and should, of course, release it for each
4901
successful acquisition).</simpara>
4902
<simpara>Cf. <function role="unix">pthread_mutex_init</function>.</simpara>
4903
</listitem></varlistentry>
4904
<varlistentry id="mutex-name"><term><code>(&mutex-name; &thr;)</code></term>
4905
<listitem><simpara>Return the &name-r; of the &mutex;.
4906
</simpara></listitem></varlistentry>
4907
<varlistentry id="mutex-lock"><term><code>(&mutex-lock; &mutex-r;
4908
&key-amp; &timeout-k;)</code></term>
4909
<listitem><simpara>Acquire the &mutex-r;. If &mutex-r; is locked by
4910
another thread, the call blocks and waits up to &timeout-k; &seconds;.
4911
If &timeout-k; is not specified, waits forever.</simpara>
4912
<simpara>Return &t; on a successful locking of &mutex-r;, and &nil; on
4913
timeout.</simpara>
4914
<para>If the calling thread has already acquired &mutex-r;, then
4915
<itemizedlist><listitem><simpara>if &mutex-r; is recursive, &t; is
4916
returned (for each recursive &mutex-lock; there should be a
4917
separate &mutex-unlock;);</simpara></listitem>
4918
<listitem><simpara>If &mutex-r; is non-recursive an &err-sig; to
4919
avoid a deadlock.</simpara></listitem></itemizedlist></para>
4920
<simpara>Cf. <function role="unix">pthread_mutex_lock</function>.</simpara>
4921
</listitem></varlistentry>
4922
<varlistentry id="mutex-unlock"><term><code>(&mutex-unlock;
4923
&mutex-r;)</code></term>
4924
<listitem><simpara>Release (unlock) &mutex-r;. If the calling thread is
4925
not locking &mutex-r;, an &err-sig;.</simpara>
4926
<simpara>Cf. <function role="unix">pthread_mutex_unlock</function>.</simpara>
4927
</listitem></varlistentry>
4928
<varlistentry id="mutex-owner"><term><code>(&mutex-owner;
4929
&mutex-r;)</code></term>
4930
<listitem><simpara>Return the &thread; that owns (locks) &mutex-r;,
4931
or &nil; if &mutex-r; is not locked.</simpara>
4932
<warning><para>By the time this function returns the &mutex-r;
4933
ownership may have changed (unless the owner is the
4934
¤t-thread;). The function is mostly useful for debugging
4935
deadlocks.</para></warning></listitem></varlistentry>
4936
<varlistentry id="mutex-recursive-p"><term><code>(&mutex-recursive-p;
4937
&mutex-r;)</code></term>
4938
<listitem><simpara>Return a indicator whether &mutex-r; is recursive.
4939
</simpara></listitem></varlistentry>
4940
<varlistentry id="with-lock"><term><code>(&with-lock; (&mutex-r;)
4941
&body-amp; &body-r;)</code></term>
4942
<listitem><simpara>Execute &body-r; with &mutex-r; locked.
4943
Upon exit &mutex-r; is released. Return whatever &body-r; returns.
4944
</simpara></listitem></varlistentry>
4945
<varlistentry id="exemption"><term>&exemption;</term>
4946
<listitem><simpara>The type of the object returned by &make-exemption;.
4947
These correspond to the &posix; condition variables,
4948
see <filename role="unix">pthread.h</filename>.</simpara>
4949
<simpara>These objects allow broadcasting state from one &thread; to
4950
the others.</simpara></listitem></varlistentry>
4951
<varlistentry id="exemptionp"><term><code>(&exemptionp;
4952
&object-r;)</code></term>
4953
<listitem><simpara>Check whether the object is of type &exemption;.
4954
</simpara></listitem></varlistentry>
4955
<varlistentry id="make-exemption"><term><code>(&make-exemption;
4956
&key-amp; &name-k;)</code></term>
4957
<listitem><simpara>Create a new &exemption; object.
4958
&name-k; should be a &string-t; describing the exemption (this really
4959
helps debugging deadlocks).</simpara>
4960
<simpara>Cf. <function role="unix">pthread_cond_init</function>.</simpara>
4961
</listitem></varlistentry>
4962
<varlistentry id="exemption-name"><term><code>(&exemption-name;
4963
&thr;)</code></term>
4964
<listitem><simpara>Return the &name-r; of the &exemp-r;.
4965
</simpara></listitem></varlistentry>
4966
<varlistentry id="exemption-signal"><term><code>(&exemption-signal;
4967
&exemp-r;)</code></term>
4968
<listitem><simpara>Signal &exemp-r; object, i.e. wake up a thread blocked
4969
on waiting for &exemp-r;.</simpara>
4970
<simpara>Cf. <function role="unix">pthread_cond_signal</function>.</simpara>
4971
</listitem></varlistentry>
4972
<varlistentry id="exemption-wait"><term><code>(&exemption-wait;
4973
&exemp-r; &mutex-r; &key-amp; &timeout-k;)</code></term>
4974
<listitem><simpara>Wait for another &thread; to call &exemption-signal;
4975
or &exemption-broadcast; on &exemp-r;.
4976
&mutex-r; should be locked by the caller; otherwise an &err-sig;.
4977
The function releases the &mutex-r; and waits for &exemp-r;.
4978
On return &mutex-r; is acquired again.</simpara>
4979
<simpara>The function waits up to &timeout-k; &seconds;.
4980
If timeout is not specified, waits forever.</simpara><simpara>
4981
Returns &t; if &exemp-r; was signaled and &nil; on timeout.</simpara>
4982
<para>On &posix; it is possible to have
4983
<ulink url="http://en.wikipedia.org/wiki/Spurious_wakeup">spurious
4984
wakeup</ulink>s, i.e., this function may return &t; even though no
4985
thread called &exemption-broadcast; or &exemption-signal;.
4986
Therefore, a common idiom for using this function is <code>(&loop;
4987
:while (some-condition-is-satisfied) :do (&exemption-wait; &exemp-r;
4988
&mutex-r;))</code>.</para>
4989
<simpara>Cf. <function role="unix">pthread_cond_wait</function>.</simpara>
4990
</listitem></varlistentry>
4991
<varlistentry id="exemption-broadcast"><term><code>(&exemption-broadcast;
4992
&exemp-r;)</code></term>
4993
<listitem><simpara>Signal &exemp-r; to all threads waiting for it.</simpara>
4994
<simpara>Cf. <function role="unix">pthread_cond_broadcast</function>.
4995
</simpara></listitem></varlistentry>
4996
<varlistentry id="y-or-n-p-timeout"><term><code>(&y-or-n-p-timeout;
4997
seconds default &rest-amp; &args-r;)</code></term>
4998
<term><code>(&yes-or-no-p-timeout; seconds default &rest-amp;
4999
&args-r;)</code></term>
5000
<listitem><simpara>Similar to &y-or-n-p; and &yes-or-no-p;, but use
5001
&with-timeout; to return <replaceable>DEFAULT</replaceable> when no
5002
reply is given within timeout &seconds;.</simpara></listitem></varlistentry>
5003
<varlistentry id="with-timeout"><term><code>(&with-timeout;
5004
(seconds &body-amp; timeout-forms) &body-amp; &body-r;)</code></term>
5005
<listitem><simpara>Execute &body-r;. If it does not finish for up to
5006
&seconds;, it is interrupted and <replaceable>timeout-forms</replaceable>
5007
are executed.</simpara>
5008
<simpara>Return the values of the last evaluated form in either
5009
&body-r; or <replaceable>timeout-forms</replaceable>.</simpara>
5010
<warning><para>Since on timeout the current thread is interrupted,
5011
special care may be needed for ensuring proper cleanup in &body-r;.
5012
See &thread-interrupt; and &with-deferred-interrupts;.</para></warning>
5013
</listitem></varlistentry>
5014
<varlistentry id="symbol-value-thread"><term><code>(&setf;
5015
(&symbol-value-thread; &symbol-r; &thr;) &value-r;)</code></term>
5016
<term><code>(&symbol-value-thread; &symbol-r; &thr;)</code></term>
5017
<listitem><simpara>Access or set the &thr-var; value.
5018
When &thr; is &t;, use the ¤t-thread;; if it is &nil;, use the
5019
&glob-var; binding.
5020
Returns two values: the &symbol-r; binding and an indicator: &nil; if
5021
not bound in the &thr;, &t; if bound, and &symbol-t; &makunbound; if
5022
the &thr-var; binding was removed with &makunbound;.
5023
</simpara></listitem></varlistentry>
5024
<varlistentry id="default-special-bindings">
5025
<term>&default-special-bindings;</term>
5026
<listitem><simpara>The default <constant>:INITIAL-BINDINGS</constant>
5027
argument of &make-thread;.</simpara></listitem></varlistentry>
5028
<varlistentry id="with-deferred-interrupts"><term>
5029
<code>(&with-deferred-interrupts; &body-amp; &body-r;)</code></term>
5030
<listitem><simpara>Defer thread interrupts (but ¬-e; thread
5031
preemption) while &body-r; is executed. If there is an interrupt
5032
while &body-r; is run, it is queued and will be executed after
5033
&body-r; finishes.</simpara>
5034
<warning><para>Care is needed if waiting or blocking in &body-r;,
5035
since there is no way to interrupt it (in case of a deadlock).
5036
The macro was added to avoid partial &unwind-protect;'s cleanup
5037
forms evaluation in case they are interrupted with a non-local exit.
5038
</para></warning></listitem></varlistentry>
5039
</variablelist></section>
5040
</section>
5041
4523
5042
<section id="quickstart"><title>Quickstarting delivery with &clisp;</title>
4524
5043
4525
5044
<para>This section describes three ways to turn &clisp; programs into
4617
5136
to a &list-t; of &string-t;s, representing the arguments given to the
4618
5137
Lisp script (i.e., <envar>$1</envar> in &sh; becomes <code>(&first;
4619
5138
&args;)</code> etc).</simpara></listitem>
4620
<listitem><simpara>The standard &unix; i/o facilities
4621
(see <filename role="unix">stdio.h</filename>) are used:
4622
&standard-input-var; is bound to &stdin;,
4623
&standard-output-var; to &stdout;, and
4624
&error-output-var; to &stderr;.
5139
<listitem><simpara>The standard &unix; i/o facilities (see &stdio;)
5140
are used: &standard-input-var; is bound to &stdin;,
5141
&standard-output-var; to &stdout;, and &error-output-var; to &stderr;.
4625
5142
Note <xref linkend="dribble-script"/>.</simpara></listitem>
4626
5143
<listitem><simpara>The &cont-err;s will be turned into &warning-t;s
4627
5144
(using &appease-cerrors;).</simpara></listitem>
4628
<listitem><simpara>Non-&cont-err;s and
4629
<keycombo>&ctrl;<keysym>C</keysym></keycombo> interrupts will
5145
<listitem><simpara>Non-&cont-err;s and &ctrl-c; interrupts will
4630
5146
terminate the execution of the Lisp script with an error status
4631
5147
(using &exit-on-error;).</simpara></listitem>
4632
5148
<listitem><simpara>If you wish the script's contents to be compiled
4700
5216
be able to do (as <literal role="login">root</literal>; you might want to put
4701
5217
these lines into <filename>/etc/rc.d/rc.local</filename>):
4702
5218
4703
<screen>
4704
<prompt>#</prompt> echo ":CLISP:E::fas::/usr/local/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register
4705
<prompt>#</prompt> echo ":CLISP:E::lisp::/usr/local/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register
4706
</screen></para>
5219
<screen><prompt>#</prompt> echo ":CLISP:E::fas::/usr/local/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register
5220
<prompt>#</prompt> echo ":CLISP:E::lisp::/usr/local/bin/clisp:" >> /proc/sys/fs/binfmt_misc/register</screen></para>
4707
5221
4708
5222
<para>Then you can do the following:
4709
<screen>
4710
&sh-prompt; cat << EOF > hello.lisp
5223
<screen>&sh-prompt; cat << EOF > hello.lisp
4711
5224
(print "hello, world!")
4712
5225
EOF
4713
5226
&sh-prompt; clisp -c hello.lisp
4714
5227
;; Compiling file hello.lisp ...
4715
;; Wrote file hello.lisp
5228
;; Wrote file hello.fas
4716
5229
0 errors, 0 warnings
4717
5230
&sh-prompt; chmod +x hello.fas
4718
5231
&sh-prompt; hello.fas
4719
5232
4720
"hello, world!"
4721
&sh-prompt;
4722
</screen></para>
5233
"hello, world!"</screen></para>
4723
5234
4724
5235
<para>Please read
4725
<ulink url="http://www.linuxhq.com/kernel/file/Documentation/binfmt_misc.txt">
5236
<ulink url="http://www.kernel.org/doc/Documentation/binfmt_misc.txt">
4726
5237
<filename>/usr/src/linux/Documentation/binfmt_misc.txt</filename></ulink>
4727
5238
for details.</para>
4728
5239
</section>
4839
5350
&stream-t; is returned.
4840
5351
If &stream-k; was specified for both &input-k; and &output-k;, three
4841
5352
Lisp &stream-t;s are returned, as for the function &mk-pipe-io;.
4842
Otherwise, the return value depends on the process termination
4843
status: if it ended normally (without signal, core-dump etc), its exit
4844
status is returned as an &integer-t;, otherwise &nil; is returned.</para>
5353
Otherwise, the return value depends on the process termination status:
5354
if it exited on a signal or a core-dump,
5355
the signal number is returned as a negative &integer-t;,
5356
else, if it ended normally with 0 exit status, &nil; is returned;
5357
otherwise, the status is returned as a positive &integer-t;.</para>
4845
5358
<para>This use of &run-prog; can cause
4846
5359
<link linkend="deadlock">deadlocks</link>, see &mk-pipe-io;.</para>
4847
5360
</listitem></varlistentry>
4901
5414
4902
5415
<para>The macro
4903
5416
<firstterm>&with-print;<indexterm id="with-print" significance="preferred">
4904
<primary id="with-print-i"><function>WITH-OUTPUT-TO-PRINTER</function>
5417
<primary><function>WITH-OUTPUT-TO-PRINTER</function>
4905
5418
</primary></indexterm></firstterm>:
4906
5419
<programlisting language="lisp">
4907
5420
(&with-print; (&var-r; [&extfmt;])
Loggerhead is a web-based interface for Breezy
Version: 2.0.1