source: trunk/source/doc/src/platform-notes.xml @ 8820

Last change on this file since 8820 was 8820, checked in by jaj, 12 years ago

This commit includes support for docbook 4.5, stylesheet changes, and updated documentation.

In order to support docbook 4.5 in nXML mode, I have added a new directory called docbook-rng-4.5 and changed schemas.xml to point to it. This should just work when editing the documentation in EMACS.

The two most obvious changes to the stylesheets are that the table of contents for each chapter now occurs at the beginning of the chapter, and the format for refentries is cleaner and more concise.

I think that we should consistently use refentry elements for all of the definitions of functions, macros, variables, etc. This retains the structured data for the definitions that can be reformatted to have different appearences by the stylesheets. We should also consistently use other docbook elements such as function and varname. I'm not really happy with their appearance right now, but that can be easily tweaked in the stylesheets as long as they are consistently used throughout the documentation.

File size: 42.7 KB
Line 
1<?xml version="1.0" encoding="utf-8"?>
2<!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd" [
3<!ENTITY rest "<varname>&amp;rest</varname>">
4<!ENTITY key "<varname>&amp;key</varname>">
5<!ENTITY optional "<varname>&amp;optional</varname>">
6<!ENTITY body "<varname>&amp;body</varname>">
7<!ENTITY aux "<varname>&amp;aux</varname>">
8<!ENTITY allow-other-keys "<varname>&amp;allow-other-keys</varname>">
9<!ENTITY CCL "Clozure CL">
10]>
11
12  <chapter id="Platform-specific-notes">
13    <title>Platform-specific notes</title>
14     
15
16    <sect1 id="Platform-specific-overview">
17      <title>Overview</title>
18      <para> The documentation and whatever experience you may have in
19      using &CCL; under Linux should also apply to using it under
20      Darwin/MacOS X and FreeBSD. There are some differences between
21      the platforms, and these differences are sometimes exposed in
22      the implementation.</para>
23
24      <sect2 id="differences-between-32-bit-and-64-bit-implementations">
25        <title>Differences Between 32-bit and 64-bit implementations</title>
26
27        <para>Fixnums on 32-bit systems use 30 bits and are in the
28        range XXX through YYY.  Fixnums on 64-bit systems use 61-bits
29        and are in the range XXX through YYY. (see <xref
30        linkend="Tagging-scheme"/>)</para>
31
32        <para>Since we have much larger fixnums on 64-bit systems,
33        <varname>INTERNAL-TIME-UNITS-PER-SECOND</varname> is 1000000
34        on 64-bit systems but remains 1000 on 32-bit systems.  This
35        enables much finer grained timing on 64-bit systems.</para>
36      </sect2>
37
38      <sect2 id="File-system-case">
39        <title>File-system case</title>
40
41        <para>Darwin and MacOS X use HFS+ file systems by default;
42        HFS+ file systems are usually case-insensitive. Most of
43        &CCL;'s filesystem and pathname code assumes that the
44        underlying filesystem is case-sensitive; this assumption
45        extends to functions like EQUAL, which assumes that #p"FOO"
46        and #p"foo" denote different, un-EQUAL filenames. Since
47        Darwin/MacOS X can also use UFS and NFS filesystems, the
48        opposite assumption would be no more correct than the one
49        that's currently made.</para>
50        <para>Whatever the best solution to this problem turns out to
51        be, there are some practical considerations. Doing:</para>
52        <programlisting>
53? (save-application "DPPCCL")
54        </programlisting>
55        <para>on 32-bit DarwinPPC has the unfortunate side-effect of
56        trying to overwrite the Darwin &CCL; kernel, "dppccl", on a
57        case-insensitive filesystem.</para>
58        <para>To work around this, the Darwin &CCL; kernel expects
59        the default heap image file name to be the kernel's own
60        filename with the string ".image" appended, so the idiom would
61        be:</para>
62        <programlisting>
63? (save-application "dppccl.image")
64        </programlisting>
65      </sect2>
66
67      <sect2 id="Line-Termination-Characters">
68        <title>Line Termination Characters</title>
69        <para>MacOSX effectively supports two distinct line-termination
70        conventions. Programs in its Darwin substrate follow the Unix
71        convention of recognizing #\LineFeed as a line terminator; traditional
72        MacOS programs use #\Return for this purpose.  Many modern
73        GUI programs try to support several different line-termination
74        conventions (on the theory that the user shouldn't be too concerned
75        about what conventions are used an that it probably doesn't matter.
76        Sometimes this is true, other times ... not so much.
77        </para>
78        <para>&CCL; follows the Unix convention on both Darwin and
79        LinuxPPC, but offers some support for reading and writing
80        files that use other conventions (including traditional MacOS
81        conventions) as well.</para> 
82        <para>This support (and anything like it) is by nature
83        heuristic: it can successfully hide the distinction between
84        newline conventions much of the time, but could mistakenly
85        change the meaning of otherwise correct programs (typically
86        when files contain both #\Return and #\Linefeed characters or
87        when files contain mixtures of text and binary data.) Because
88        of this concern, the default settings of some of the variables
89        that control newline translation and interpretation are
90        somewhat conservative.</para>
91        <para>Although the issue of multiple newline conventions
92        primarily affects MacOSX users, the functionality described
93        here is available under LinuxPPC as well (and may occasionally
94        be useful there.)</para> <para>None of this addresses issues
95        related to the third newline convention ("CRLF") in widespread
96        use (since that convention isn't native to any platform on
97        which &CCL; currently runs). If &CCL; is ever ported to
98        such a platform, that issue might be revisited.</para>
99        <para>Note that some MacOS programs (including some versions
100        of commercial MCL) may use HFS file type information to
101        recognize TEXT and other file types and so may fail to
102        recognize files created with &CCL; or other Darwin
103        applications (regardless of line termination issues.)</para>
104        <para>Unless otherwise noted, the symbols mentioned in this
105        documentation are exported from the CCL package.</para>
106      </sect2>
107
108      <sect2 id="Single-precision-trig---transcendental-functions">
109        <title>Single-precision trig &amp; transcendental functions</title>
110        <para>
111        Despite what Darwin's man pages say, early versions of its math library
112        (up to and including at least OSX 10.2 (Jaguar) don't implement
113        single-precision variants of the transcendental and trig functions
114        (#_sinf, #_atanf, etc.) &CCL; worked around this by coercing
115        single-precision args to double-precision, calling the
116        double-precision version of the math library function, and coercing
117        the result back to a SINGLE-FLOAT. These steps can introduce rounding
118        errors (and potentially overflow conditions) that might not be present
119        or as severe if true 32-bit variants were available.</para>
120      </sect2>
121
122      <sect2 id="Shared-libraries">
123        <title>Shared libraries</title>
124        <para>Darwin/MacOS X distinguishes between "shared libraries"
125        and "bundles" or "extensions"; Linux and FreeBSD don't. In
126        Darwin, "shared libraries" have the file type "dylib" : the
127        expectation is that this class of file is linked against when
128        executable files are created and loaded by the OS when the
129        executable is launched. The latter class -
130        "bundles/extensions" - are expected to be loaded into and
131        unloaded from a running application, via a mechanism like the
132        one used by &CCL;'s OPEN-SHARED-LIBRARY function.</para>
133      </sect2>
134    </sect1>
135
136    <sect1 id="Unix-Posix-Darwin-Features">
137      <title>Unix/Posix/Darwin Features</title>
138      <para>&CCL; has several convenience functions which allow you
139      to make Posix (portable Unix) calls without having to use the
140      foreign-function interface.  Each of these corresponds directly
141      to a single Posix function call, as it might be made in C.
142      There is no attempt to make these calls correspond to Lisp
143      idioms, such as <literal>setf</literal>.  This means that their
144      behaviour is simple and predictable.</para>
145      <para>For working with environment variables, there are
146      CCL::GETENV and CCL::SETENV.</para>
147      <para>For working with user and group IDs, there are
148      CCL::GETUID, CCL::SETUID, and CCL::SETGID.  To find the home
149      directory of an arbitrary user, as set in the user database
150      (/etc/passwd), there is CCL::GET-USER-HOME-DIR.</para>
151      <para>For process IDs, there is CCL::GETPID.</para>
152      <para>For the <literal>system()</literal> function, there is
153      CCL::OS-COMMAND.  Ordinarily, it is better - both more efficient
154      and more predictable - to use the features described in <xref
155      linkend="Running-Other-Programs-as-Subprocesses"/>.  However,
156      sometimes you may want to specifically ask the shell to invoke a
157      command for you.</para>
158    </sect1>
159
160    <sect1 id="Cocoa-Programming-in-CCL">
161      <title>Cocoa Programming in &CCL;</title>
162      <para>Cocoa is one of Apple's APIs for GUI programming; for most
163      purposes, development is considerably faster with Cocoa than
164      with the alternatives.  You should have a little familiarity
165      with it, to better understand this section.</para>
166      <para>A small sample Cocoa program can be invoked by evaluating
167      (REQUIRE 'TINY) and then (CCL::TINY-SETUP). This program
168      provides a simple example of using several of the bridge's
169      capabilities.</para>
170      <para>The Tiny demo creates Cocoa objects dynamically, at
171      runtime, which is always an option.  However, for large
172      applications, it is usually more convenient to create your
173      objects with Apple Interface Builder, and store them in .nib
174      files to be loaded when needed.  Both approaches can be freely
175      mixed in a single program.</para>
176
177      <sect2 id="The-Command-Line-and-the-Window-System">
178        <title>The Command Line and the Window System</title>
179        <para>&CCL; is ordinarily a command-line application (it
180        doesn't have a connection to the OSX Window server, doesn't
181        have its own menubar or dock icon, etc.) By opening some
182        libraries and jumping through some hoops, it's able to sort of
183        transform itself into a full-fledged GUI application (while
184        retaining its original TTY-based listener.) The general idea
185        is that this hybrid environment can be used to test and
186        protoype UI ideas and the resulting application can eventually
187        be fully transformed into a bundled, double-clickable
188        application. This is to some degree possible, but there needs
189        to be a bit more infrastructure in place before many people
190        would find it easy.</para>
191        <para>Cocoa applications use the NSLog function to write
192        informational/warning/error messages to the application's
193        standard output stream. When launched by the Finder, a GUI
194        application's standard output is diverted to a logging
195        facility that can be monitored with the Console application
196        (found in /Applications/Utilities/Console.app).  In the hybrid
197        environment, the application's standard output stream is
198        usually the initial listener's standard output stream. With
199        two different buffered stream mechanisms trying to write to
200        the same underlying Unix file descriptor, it's not uncommon to
201        see NSLog output mixed with lisp output on the initial
202        listener.</para>
203      </sect2>
204
205      <sect2 id="Writing--and-reading--Cocoa-code">
206        <title>Writing (and reading) Cocoa code</title> <para>The
207        syntax of the constructs used to define Cocoa classes and
208        methods has changed a bit (it was never documented outside of
209        the source code and never too well documented at all), largely
210        as the result of functionality offered by Randall Beer's
211        bridge; the &ldquo;standard name-mapping conventions&rdquo;
212        referenced below are described in his CocoaBridgeDoc.txt file,
213        as are the constructs used to invoke (&ldquo;send messages
214        to&rdquo;) Cocoa methods.</para>
215        <para>All of the symbols described below are currently internal to
216the CCL package.</para>
217        <simplelist type="vert" columns="1">
218          <member><xref linkend="m_class"/></member>
219          <member><xref linkend="m_selector"/></member>
220          <member><xref linkend="m_define-objc-method"/></member>
221          <member><xref linkend="m_define-objc-class-method"/></member>
222        </simplelist>
223      </sect2>
224
225      <sect2 id="The-Application-Kit-and-Multiple-Threads">
226        <title>The Application Kit and Multiple Threads</title>
227        <para>The Cocoa API is broken into several pieces.  The
228        Application Kit, affectionately called AppKit, is the one
229        which deals with window management, drawing, and handling
230        events.  AppKit really wants all these things to be done by a
231        "distinguished thread".  creation, and drawing to take place
232        on a distinguished thread.</para>
233        <para>Apple has published some guidelines which discuss these
234        issues in some detail; see the Apple Multithreading
235        Documentation, and in particular the guidelines on Using the
236        Application Kit from Multiple Threads.  The upshot is that
237        there can sometimes be unexpected behavior when objects are
238        created in threads other than the distinguished event thread;
239        eg, the event thread sometimes starts performing operations on
240        objects that haven't been fully initialized.</para> <para>It's
241        certainly more convenient to do certain types of exploratory
242        programming by typing things into a listener or evaluating a
243        &ldquo;defun&rdquo; in an Emacs buffer; it may sometimes be
244        necessary to be aware of this issue while doing so.</para>
245        <para>Each thread in the Cocoa runtime system is expected to
246        maintain a current &ldquo;autorelease pool&rdquo; (an instance
247        of the NSAutoreleasePool class); newly created objects are
248        often added to the current autorelease pool (via the
249        -autorelease method), and periodically the current autorelease
250        pool is sent a &ldquo;-release&rdquo; message, which causes it
251        to send &ldquo;-release&rdquo; messages to all of the objects
252        that've been added to it.</para>
253        <para>If the current thread doesn't have a current autorelease
254        pool, the attempt to autorelease any object will result in a
255        severe-looking warning being written via NSLog. The event
256        thread maintains an autorelease pool (it releases the current
257        pool after each event is processed and creates a new one for
258        the next event), so code that only runs in that thread should
259        never provoke any of these severe-looking NSLog
260        messages.</para> <para>To try to suppress these messages (and
261        still participate in the Cocoa memory management scheme), each
262        listener thread (the initial listener and any created via the
263        &ldquo;New Listener&rdquo; command in the IDE) is given a
264        default autorelease pool; there are REPL colon-commands for
265        manipulating the current listener's &ldquo;toplevel
266        auturelease pool&rdquo;.</para>
267        <para>In the current scheme, every time that Cocoa calls lisp
268        code, a lisp error handler is established which maps any lisp
269        conditions to ObjC exceptions and arranges that this exception
270        is raised when the callback to lisp returns. Whenever lisp
271        code invokes a Cocoa method, it does so with an ObjC exception
272        handler in place; this handler maps ObjC exceptions to lisp
273        conditions and signals those conditions.</para> <para>Any
274        unhandled lisp error or ObjC exception that occurs during the
275        execution of the distinguished event thread's event loop
276        causes a message to be NSLog'ed and the event loop to (try to)
277        continue execution. Any error that occurs in other threads is
278        handled at the point of the outermost Cocoa method
279        invocation. (Note that the error is not necessarily
280        &ldquo;handled&rdquo; in the dynamic context in which it
281        occurs.)</para>
282        <para>Both of these behaviors could possibly be improved; both of them
283seem to be substantial improvements over previous behaviors (where,
284for instance, a misspelled message name typically terminated the
285application.)</para>
286      </sect2>
287
288      <sect2 id="Acknowledgement--2-">
289        <title>Acknowledgement</title>
290        <para>The Cocoa bridge was originally developed, and
291        generously contributed by, Randal Beer.</para>
292      </sect2>
293    </sect1>
294
295    <sect1 id="Building-an-Application-Bundle">
296      <title>Building an Application Bundle</title>
297      <para>You may have noticed that (require "COCOA") takes a long
298      time to load.  It is possible to avoid this by saving a Lisp
299      heap image which has everything already loaded.  There is an
300      example file which allows you to do this,
301      "ccl/examples/cocoa-application.lisp", by producing a
302      double-clickable application which runs your program.  First,
303      load your own program.  Then, do:</para>
304      <programlisting>
305? (require "COCOA-APPLICATION")
306      </programlisting>
307      <para>When it finishes, you should be able to double-click the &CCL; icon
308in the ccl directory, to quickly start your program.</para>
309      <para>The OS may have already decided that &CCL;.app isn't a valid
310executable bundle, and therefore won't let you double-click it.
311If this happens to you, to force it to reconsider, just update the
312last-modified time of the bundle.  In Terminal:</para>
313      <programlisting>> touch &CCL;.app
314</programlisting>
315      <para>There is one important caveat.</para>
316      <para>Because of the way that the ObjC bridge currently works, a saved
317image is dependent upon the <emphasis>exact</emphasis> versions of
318the Cocoa libraries which were present when it was saved.
319Specifically, the interface database is.  So, for example, an
320application produced under OS X 10.3.5 will not work under
321OS X 10.3.6.  This is inconvenient when you wish to distribute an
322application you have built this way.</para>
323      <para>Work in this direction is ongoing.  It is worth looking at the project
324"Bosco", by Mikel Evins, which is a template that can be used to build
325application bundles in a different way.  It is
326available here, as part
327of the "Clotho" project, and there is
328here.</para>
329      <para>When an image which had contained ObjC classes (which are also
330CLOS classes) is re-launched, those classes are "revived": all
331preexisting classes have their addresses updated destructively, so that
332existing subclass/superclass/metaclass relationships are maintained.
333It's not possible (and may never be) to preserve foreign
334instances across SAVE-APPLICATION. (It may be the case that NSArchiver
335and NSCoder and related classes offer some approximation of that.)</para>
336    </sect1>
337
338    <sect1 id="Recommended-Reading">
339      <title>Recommended Reading></title>
340      <variablelist>
341        <varlistentry>
342           <term>
343             <ulink url="http://developer.apple.com/documentation/Cocoa/">Cocoa Documentation</ulink>
344           </term>
345
346           <listitem>
347             <para>
348               This is the top page for all of Apple's documentation on
349               Cocoa.  If you are unfamiliar with Cocoa, it is a good
350               place to start.
351             </para>
352           </listitem>
353        </varlistentry>
354        <varlistentry>
355          <term>
356            <ulink url="http://developer.apple.com/documentation/Cocoa/Reference/Foundation/ObjC_classic/index.html">Foundation Reference for Objective-C</ulink>
357          </term>
358
359          <listitem>
360            <para>
361              This is one of the two most important Cocoa references; it
362              covers all of the basics, except for GUI programming.  This is
363              a reference, not a tutorial.
364            </para>
365          </listitem>
366        </varlistentry>
367
368        <varlistentry>
369          <term>
370            <ulink url="http://developer.apple.com/documentation/Cocoa/Reference/ApplicationKit/ObjC_classic/index.html">Application Kit Reference for Objective-C</ulink>
371          </term>
372
373          <listitem>
374            <para>
375              This is the other; it covers GUI programming with Cocoa
376              in considerable depth.  This is a reference, not a tutorial.
377            </para>
378          </listitem>
379        </varlistentry>
380
381        <varlistentry>
382          <term>
383            <ulink url="http://developer.apple.com/documentation/index.html">Apple Developer Documentation</ulink>
384          </term>
385
386          <listitem>
387            <para>
388              This is the site which the above two documents are found on;
389              go here to find the documentation on any other Apple API.
390              Also go here if you need general guidance about OS X, Carbon,
391              Cocoa, Core Foundation, or Objective C.
392            </para>
393          </listitem>
394        </varlistentry>
395      </variablelist>
396
397    </sect1>
398
399    <sect1 id="Operating-System-Dictionary">
400      <title>Operating-System Dictionary</title>
401
402      <refentry id="f_getenv">
403        <indexterm zone="f_getenv">
404          <primary>getenv</primary>
405        </indexterm>
406
407        <refnamediv>
408          <refname>CCL::GETENV</refname>
409          <refpurpose></refpurpose>
410          <refclass>Function</refclass>
411        </refnamediv>
412
413        <refsynopsisdiv>
414          <synopsis><function>getenv</function> name => value</synopsis>
415        </refsynopsisdiv>
416
417        <refsect1>
418          <title>Arguments and Values</title>
419
420          <variablelist>
421            <varlistentry>
422              <term>name</term>
423
424              <listitem>
425                <para>a string which is the name of an existing
426                environment variable;
427                case-sensitive</para>
428              </listitem>
429            </varlistentry>
430
431            <varlistentry>
432              <term>value</term>
433
434              <listitem>
435                <para>if there is an environment variable named
436                <varname>name</varname>, its value, as a string; if there
437                is not, NIL</para>
438              </listitem>
439            </varlistentry>
440          </variablelist>
441        </refsect1>
442
443        <refsect1>
444          <title>Description</title>
445
446          <para>
447            Looks up the value of the environment variable named by
448            <varname>name</varname>, in the OS environment.
449          </para>
450        </refsect1>
451      </refentry>
452
453      <refentry id="f_setenv">
454        <indexterm zone="f_setenv">
455          <primary>setenv</primary>
456        </indexterm>
457
458        <refnamediv>
459          <refname>CCL::SETENV</refname>
460          <refpurpose></refpurpose>
461          <refclass>Function</refclass>
462        </refnamediv>
463
464        <refsynopsisdiv>
465          <synopsis><function>setenv</function> name value => errno</synopsis>
466        </refsynopsisdiv>
467
468        <refsect1>
469          <title>Arguments and Values</title>
470
471          <variablelist>
472            <varlistentry>
473              <term>name</term>
474
475              <listitem>
476                <para>a string which is the name of a new or existing
477                environment variable;
478                case-sensitive</para>
479              </listitem>
480            </varlistentry>
481
482            <varlistentry>
483              <term>value</term>
484
485              <listitem>
486                <para>a string, to be the new value of the
487                environment variable
488                named by <varname>name</varname></para>
489              </listitem>
490            </varlistentry>
491
492            <varlistentry>
493              <term>errno</term>
494
495              <listitem>
496                <para>zero if the function call completes successfully;
497                otherwise, a platform-dependent integer which describes
498                the problem</para>
499              </listitem>
500            </varlistentry>
501          </variablelist>
502        </refsect1>
503
504        <refsect1>
505          <title>Description</title>
506
507          <para>
508            Sets the value of the environment variable named by
509            <varname>name</varname>, in the OS environment.  If there is
510            no such environment
511            variable, creates it.
512          </para>
513        </refsect1>
514      </refentry>
515
516      <refentry id="f_current-directory-name">
517        <indexterm zone="f_current-directory-name">
518          <primary>current-directory-name</primary>
519        </indexterm>
520
521        <refnamediv>
522          <refname>CCL::CURRENT-DIRECTORY-NAME</refname>
523          <refpurpose></refpurpose>
524          <refclass>Function</refclass>
525        </refnamediv>
526
527        <refsynopsisdiv>
528          <synopsis><function>current-directory-name</function>
529          => path</synopsis>
530        </refsynopsisdiv>
531
532        <refsect1>
533          <title>Values</title>
534
535          <variablelist>
536            <varlistentry>
537              <term>path</term>
538
539              <listitem>
540                <para>a string, an absolute pathname in Posix format - with
541                directory components separated by slashes</para>
542              </listitem>
543            </varlistentry>
544          </variablelist>
545        </refsect1>
546
547        <refsect1>
548          <title>Description</title>
549
550          <para>
551            Looks up the current working directory of the &CCL; process;
552            unless it has been changed, this is the directory &CCL; was
553            started in.
554          </para>
555        </refsect1>
556      </refentry>
557
558      <refentry id="f_getuid">
559        <indexterm zone="f_getuid">
560          <primary>getuid</primary>
561        </indexterm>
562
563        <refnamediv>
564          <refname>CCL::GETUID</refname>
565          <refpurpose></refpurpose>
566          <refclass>Function</refclass>
567        </refnamediv>
568
569        <refsynopsisdiv>
570          <synopsis><function>getuid</function> => uid</synopsis>
571        </refsynopsisdiv>
572
573        <refsect1>
574          <title>Values</title>
575
576          <variablelist>
577            <varlistentry>
578              <term>uid</term>
579
580              <listitem>
581                <para>a non-negative integer, identifying a specific user
582                account as defined in the OS user database</para>
583              </listitem>
584            </varlistentry>
585          </variablelist>
586        </refsect1>
587
588        <refsect1>
589          <title>Description</title>
590
591          <para>
592            Returns the ("real") user ID of the current user.
593          </para>
594        </refsect1>
595      </refentry>
596
597      <refentry id="f_setuid">
598        <indexterm zone="f_setuid">
599          <primary>setuid</primary>
600        </indexterm>
601
602        <refnamediv>
603          <refname>CCL::SETUID</refname>
604          <refpurpose></refpurpose>
605          <refclass>Function</refclass>
606        </refnamediv>
607
608        <refsynopsisdiv>
609          <synopsis><function>setuid</function> uid => errno</synopsis>
610        </refsynopsisdiv>
611
612        <refsect1>
613          <title>Arguments and Values</title>
614
615          <variablelist>
616            <varlistentry>
617              <term>uid</term>
618
619              <listitem>
620                <para>a non-negative integer, identifying a specific user
621                account as defined in the OS user database</para>
622              </listitem>
623            </varlistentry>
624
625            <varlistentry>
626              <term>errno</term>
627
628              <listitem>
629                <para>zero if the function call completes successfully;
630                otherwise, a platform-dependent integer which describes
631                the problem</para>
632              </listitem>
633            </varlistentry>
634          </variablelist>
635        </refsect1>
636
637        <refsect1>
638          <title>Description</title>
639
640          <para>
641            Attempts to change the current user ID (both "real" and
642            "effective"); fails unless
643            the &CCL; process has super-user privileges or the ID
644            given is that of the current user.
645          </para>
646        </refsect1>
647      </refentry>
648
649      <refentry id="f_setgid">
650        <indexterm zone="f_setgid">
651          <primary>setgid</primary>
652        </indexterm>
653
654        <refnamediv>
655          <refname>CCL::SETGID</refname>
656          <refpurpose></refpurpose>
657          <refclass>Function</refclass>
658        </refnamediv>
659
660        <refsynopsisdiv>
661          <synopsis><function>setgid</function> gid => errno</synopsis>
662        </refsynopsisdiv>
663
664        <refsect1>
665          <title>Arguments and Values</title>
666
667          <variablelist>
668            <varlistentry>
669              <term>gid</term>
670
671              <listitem>
672                <para>a non-negative integer, identifying a specific
673                group as defined in the OS user database</para>
674              </listitem>
675            </varlistentry>
676
677            <varlistentry>
678              <term>errno</term>
679
680              <listitem>
681                <para>zero if the function call completes successfully;
682                otherwise, a platform-dependent integer which describes
683                the problem</para>
684              </listitem>
685            </varlistentry>
686          </variablelist>
687        </refsect1>
688
689        <refsect1>
690          <title>Description</title>
691
692          <para>
693            Attempts to change the current group ID (both "real" and
694            "effective"); fails unless
695            the &CCL; process has super-user privileges or the ID
696            given is that of a group to which the current user belongs.
697          </para>
698        </refsect1>
699      </refentry>
700
701      <refentry id="f_getpid">
702        <indexterm zone="f_getpid">
703          <primary>getpid</primary>
704        </indexterm>
705
706        <refnamediv>
707          <refname>CCL::GETPID</refname>
708          <refpurpose></refpurpose>
709          <refclass>Function</refclass>
710        </refnamediv>
711
712        <refsynopsisdiv>
713          <synopsis><function>getpid</function> => pid</synopsis>
714        </refsynopsisdiv>
715
716        <refsect1>
717          <title>Values</title>
718
719          <variablelist>
720            <varlistentry>
721              <term>pid</term>
722
723              <listitem>
724                <para>a non-negative integer, identifying an OS process</para>
725              </listitem>
726            </varlistentry>
727          </variablelist>
728        </refsect1>
729
730        <refsect1>
731          <title>Description</title>
732
733          <para>
734            Returns the ID of the &CCL; OS process.
735          </para>
736        </refsect1>
737      </refentry>
738
739      <refentry id="f_get-user-home-dir">
740        <indexterm zone="f_get-user-home-dir">
741          <primary>get-user-home-dir</primary>
742        </indexterm>
743
744        <refnamediv>
745          <refname>CCL::GET-USER-HOME-DIR</refname>
746          <refpurpose></refpurpose>
747          <refclass>Function</refclass>
748        </refnamediv>
749
750        <refsynopsisdiv>
751          <synopsis><function>get-user-home-dir</function> 
752          uid => path</synopsis>
753        </refsynopsisdiv>
754
755        <refsect1>
756          <title>Values</title>
757
758          <variablelist>
759            <varlistentry>
760              <term>uid</term>
761
762              <listitem>
763                <para>a non-negative integer, identifying a specific user
764                account as defined in the OS user database</para>
765              </listitem>
766            </varlistentry>
767            <varlistentry>
768              <term>path</term>
769
770              <listitem>
771                <para>a string, an absolute pathname in Posix format - with
772                directory components separated by slashes; or NIL</para>
773              </listitem>
774            </varlistentry>
775          </variablelist>
776        </refsect1>
777
778        <refsect1>
779          <title>Description</title>
780
781          <para>
782            Looks up and returns the defined home directory of the user
783            identified by <varname>uid</varname>.  This value comes from the
784            OS user database, not from the <varname>$HOME</varname>
785            environment variable.  Returns NIL if there is no user with
786            the ID <varname>uid</varname>.
787          </para>
788        </refsect1>
789      </refentry>
790
791      <refentry id="f_os-command">
792        <indexterm zone="f_os-command">
793          <primary>os-command</primary>
794        </indexterm>
795
796        <refnamediv>
797          <refname>CCL::OS-COMMAND</refname>
798          <refpurpose></refpurpose>
799          <refclass>Function</refclass>
800        </refnamediv>
801
802        <refsynopsisdiv>
803          <synopsis><function>os-command</function> command-line
804          => exit-code</synopsis>
805        </refsynopsisdiv>
806
807        <refsect1>
808          <title>Values</title>
809
810          <variablelist>
811            <varlistentry>
812              <term>command-line</term>
813
814              <listitem><para>a string, obeying all the whitespace and
815              escaping
816              conventions required by the user's default system shell</para>
817              </listitem>
818            </varlistentry>
819          </variablelist>
820          <variablelist>
821            <varlistentry>
822              <term>exit-code</term>
823
824              <listitem><para>a non-negative integer, returned as the exit
825              code of a subprocess; zero indicates success</para></listitem>
826            </varlistentry>
827          </variablelist>
828        </refsect1>
829
830        <refsect1>
831          <title>Description</title>
832
833          <para>
834            Invokes the Posix function <function>system()</function>, which
835            invokes the user's default system shell (such as
836            sh or tcsh) as a new process, and has that shell execute
837            <varname>command-line</varname>.
838          </para>
839         
840          <para>
841            If the shell was able to find the command specified in
842            <varname>command-line</varname>, then <varname>exit-code</varname>
843            is the exit code of that command.  If not, it is the exit
844            code of the shell itself.
845          </para>
846        </refsect1>
847
848        <refsect1>
849          <title>Notes</title>
850
851          <para>
852            By convention, an exit code of 0 indicates success.  There are
853            also other conventions; unfortunately, they are OS-specific, and
854            the portable macros to decode their meaning are implemented
855            by the system headers as C preprocessor macros.  This means
856            that there is no good, automated way to make them available
857            to Lisp.
858          </para>
859        </refsect1>
860      </refentry>
861
862      <refentry id="m_class">
863        <indexterm zone="m_class">
864          <primary>@class</primary>
865        </indexterm>
866       
867        <refnamediv>
868          <refname>CCL::@CLASS</refname>
869          <refpurpose></refpurpose>
870          <refclass>Macro</refclass>
871        </refnamediv>
872
873        <refsynopsisdiv>
874          <synopsis><function>@class</function> class-name</synopsis>
875        </refsynopsisdiv>
876
877        <refsect1>
878          <title>Arguments and Values</title>
879
880          <variablelist>
881            <varlistentry>
882              <term>class-name</term>
883
884              <listitem>
885                <para>a string which denotes an existing class name, or a
886                symbol which can be mapped to such a string via the standard
887                name-mapping conventions for class names</para>
888              </listitem>
889            </varlistentry>
890          </variablelist>
891        </refsect1>
892
893        <refsect1>
894          <title>Description</title>
895
896          <para>Used to refer to a known ObjC class by name. (Via the use
897          LOAD-TIME-VALUE, the results of a class-name -&#62; class lookup
898          are cached.)</para>
899
900          <para>
901            <function>@class</function> is obsolete as of late 2004, because
902            find-class now works on ObjC classes.  It is described here
903            only because some old code still uses it.
904          </para>
905        </refsect1>
906        </refentry>
907
908        <refentry id="m_selector">
909          <indexterm zone="m_selector">
910            <primary>@selector</primary>
911          </indexterm>
912
913          <refnamediv>
914            <refname>CCL::@SELECTOR</refname>
915            <refpurpose></refpurpose>
916            <refclass>Macro</refclass>
917          </refnamediv>
918
919          <refsynopsisdiv>
920            <synopsis><function>@selector</function> string</synopsis>
921          </refsynopsisdiv>
922
923          <refsect1>
924            <title>Arguments and Values</title>
925
926            <variablelist>
927              <varlistentry>
928                <term>string</term>
929
930                <listitem>
931                  <para>a string constant, used to canonically refer to an
932                  ObjC method selector</para>
933                </listitem>
934              </varlistentry>
935            </variablelist>
936          </refsect1>
937
938          <refsect1>
939            <title>Description</title>
940
941            <para>Used to refer to an ObjC method selector (method name). Uses
942            LOAD-TIME-VALUE to cache the result of a string -&#62; selector
943            lookup.</para>
944          </refsect1>
945        </refentry>
946
947        <refentry id="m_define-objc-method">
948          <indexterm zone="m_define-objc-method">
949            <primary>define-objc-method</primary>
950          </indexterm>
951
952          <refnamediv>
953            <refname>CCL::DEFINE-OBJC-METHOD</refname>
954            <refpurpose></refpurpose>
955            <refclass>Macro</refclass>
956          </refnamediv>
957
958          <refsynopsisdiv>
959            <synopsis><function>define-objc-method</function>
960            (selector class-name) &body; body</synopsis>
961          </refsynopsisdiv>
962
963          <refsect1>
964            <title>Arguments and Values</title>
965
966            <variablelist>
967              <varlistentry>
968                <term>selector</term>
969
970                <listitem>
971                  <para>either a string which represents the name of the
972                  selector or a list which describ+es the method's return
973                  type, selector components, and argument types (see below.)
974                  If the first form is used, then the first form in the body
975                  must be a list which describes the selector's argument
976                  types and return value type, as per DEFCALLBACK.</para>
977                </listitem>
978              </varlistentry>
979
980              <varlistentry>
981                <term>class-name</term>
982
983                <listitem>
984                  <para>either a string which names an existing ObjC class
985                  name or a list symbol which can map to such a string via the
986                  standard name-mapping conventions for class names. (Note
987                  that the "canonical" lisp class name is such a
988                  symbol)</para>
989                </listitem>
990              </varlistentry>
991            </variablelist>
992          </refsect1>
993
994          <refsect1>
995            <title>Description</title>
996
997            <para>Defines an ObjC-callable method which implements the
998            specified message selector for instances of the existing ObjC
999            class class-name.</para>
1000          </refsect1>
1001        </refentry>
1002
1003        <refentry id="m_define-objc-class-method">
1004          <indexterm zone="m_define-objc-class-method">
1005            <primary>define-objc-class-method</primary>
1006          </indexterm>
1007
1008          <refnamediv>
1009            <refname>CCL::DEFINE-OBJC-CLASS-METHOD</refname>
1010            <refpurpose></refpurpose>
1011            <refclass>Macro</refclass>
1012          </refnamediv>
1013
1014          <refsynopsisdiv>
1015            <synopsis><function>define-objc-class-method</function>
1016            (selector class-name) &body; body</synopsis>
1017          </refsynopsisdiv>
1018
1019          <refsect1>
1020            <title>Arguments and Values</title>
1021
1022            <para>As per DEFINE-OBJC-METHOD</para>
1023          </refsect1>
1024
1025          <refsect1>
1026            <title>Description</title>
1027
1028            <para>Like DEFINE-OBJC-METHOD, only used to define methods on the
1029            <emphasis>class</emphasis> named by class-name and on its
1030            subclasses.</para>
1031
1032            <para>For both DEFINE-OBJC-METHOD and DEFINE-OBJC-CLASS-METHOD, the
1033            "selector" argument can be a list whose first element is a
1034            foreign type specifier for the method's return value type and whose
1035            subsequent elements are either:</para>
1036
1037            <itemizedlist>
1038              <listitem>
1039                <para>a non-keyword symbol, which can be mapped to a selector string
1040                for a parameterless method according to the standard name-mapping
1041                conventions for method selectors.</para>
1042              </listitem>
1043             
1044              <listitem>
1045                <para>a list of alternating keywords and variable/type specifiers,
1046                where the set of keywords can be mapped to a selector string for a
1047                parameteriezed method according to the standard name-mapping
1048                conventions for method selectors and each variable/type-specifier is
1049                either a variable name (denoting a value of type :ID) or a list whose
1050                CAR is a variable name and whose CADR is the corresponding
1051                argument's foreign type specifier.</para>
1052              </listitem>
1053            </itemizedlist>
1054          </refsect1>
1055        </refentry>
1056
1057        <refentry id="v_alternate-line-terminator">
1058          <indexterm zone="v_alternate-line-terminator">
1059            <primary>*alternate-line-terminator*</primary>
1060          </indexterm>
1061
1062          <refnamediv>
1063            <refname>CCL:*ALTERNATE-LINE-TERMINATOR*</refname>
1064            <refpurpose></refpurpose>
1065            <refclass>Variable</refclass>
1066          </refnamediv>
1067
1068          <refsect1>
1069            <title>Description</title>
1070
1071            <para>This variable is currently only used by the standard reader macro
1072            function for #\; (single-line comments); that function reads successive
1073            characters until EOF, a #\NewLine is read, or a character EQL to the
1074            value of *alternate-line-terminator* is read. In &CCL; for Darwin, the
1075            value of this variable is initially #\Return ; in &CCL; for LinuxPPC,
1076            it&#39;s initially NIL.</para>
1077           
1078            <para>Their default treatment by the #\; reader macro is the primary way
1079            in which #\Return and #\Linefeed differ syntactally; by extending the
1080            #\; reader macro to (conditionally) treat #\Return as a
1081            comment-terminator, that distinction is eliminated. This seems to make
1082            LOAD and COMPILE-FILE insensitive to line-termination issues in many
1083            cases. It could fail in the (hopefully rare) case where a LF-terminated
1084            (Unix) text file contains embedded #\Return characters, and this
1085            mechanism isn&#39;t adequate to handle cases where newlines are embedded
1086            in string constants or other tokens (and presumably should be translated
1087            from an external convention to the external one) : it doesn&#39;t change
1088            what READ-CHAR or READ-LINE &#34;see&#34;, and that may be necessary to
1089            handle some more complicated cases.</para>
1090          </refsect1>
1091        </refentry>
1092
1093        <refentry id="k_external-format">
1094          <indexterm zone="k_external-format">
1095            <primary>:external-format</primary>
1096          </indexterm>
1097
1098          <refnamediv>
1099            <refname>:EXTERNAL-FORMAT</refname>
1100            <refpurpose></refpurpose>
1101            <refclass>Keyword Argument</refclass>
1102          </refnamediv>
1103
1104          <refsect1>
1105            <title>Description</title>
1106
1107            <para>Per ANSI CL, &CCL; supports the :EXTERNAL-FORMAT keyword
1108            argument to the functions OPEN, LOAD, and COMPILE-FILE. This argument is
1109            intended to provide a standard way of providing implementation-dependent
1110            information about the format of files opened with an element-type of
1111            CHARACTER. This argument can meaningfully take on the values :DEFAULT
1112            (the default), :MACOS, :UNIX, or :INFERRED in &CCL;.</para>
1113           
1114            <para>When defaulted to or specified as :DEFAULT, the format of the file
1115            stream is determined by the value of the variable
1116            CCL:*DEFAULT-EXTERNAL-FORMAT*. See below.</para>
1117           
1118            <para>When specified as :UNIX, all characters are read from and written
1119            to files verbatim.</para>
1120           
1121            <para>When specified as :MACOS, all #\Return characters read from the
1122            file are immediately translated to #\Linefeed (#\Newline); all #\Newline
1123            (#\Linefeed) characters are written externally as #\Return characters.</para>
1124           
1125            <para>When specified as :INFERRED and the file is open for input, the
1126            first bufferful of input data is examined; if a #\Return character
1127            appears in the buffer before the first #\Linefeed, the file stream&#39;s
1128            external-format is set to :MACOS; otherwise, it is set to :UNIX.</para>
1129           
1130            <para>All other values of :EXTERNAL-FORMAT - and any combinations that
1131            don&#39;t make sense, such as trying to infer the format of a
1132            newly-created output file stream - are treated as if :UNIX was
1133            specified. As mentioned above, the :EXTERNAL-FORMAT argument doesn&#39;t
1134            apply to binary file streams.</para>
1135           
1136            <para>The translation performed when :MACOS is specified or inferred has
1137            a somewhat greater chance of doing the right thing than the
1138            *alternate-line-terminator* mechanism does; it probably has a somewhat
1139            greater chance of doing the wrong thing, as well.</para>
1140          </refsect1>
1141        </refentry>
1142
1143        <refentry id="v_default-external-format">
1144          <indexterm zone="v_default-external-format">
1145            <primary>*default-external-format*</primary>
1146          </indexterm>
1147         
1148          <refnamediv>
1149            <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
1150            <refpurpose></refpurpose>
1151            <refclass>Variable</refclass>
1152          </refnamediv>
1153
1154          <refsect1>
1155            <title>Description</title>
1156
1157            <para>The value of this variable is used when :EXTERNAL-FORMAT is
1158            unspecified or specified as :DEFAULT. It can meaningfully be given any
1159            of the values :UNIX, :MACOS, or :INFERRED, each of which is interpreted
1160            as described above.</para>
1161           
1162            <para>Because there&#39;s some risk that unsolicited newline translation
1163            could have undesirable consequences, the initial value of this variable
1164            in &CCL; is :UNIX.</para>
1165          </refsect1>
1166        </refentry>
1167
1168        <refentry id="c_ns-lisp-string">
1169          <indexterm zone="c_ns-lisp-string">
1170            <primary>ns-lisp-string</primary>
1171          </indexterm>
1172
1173          <refnamediv>
1174            <refname>CCL::NS-LISP-STRING</refname>
1175            <refpurpose></refpurpose>
1176            <refclass>Class</refclass>
1177          </refnamediv>
1178
1179          <refsect1>
1180            <title>Superclasses</title>
1181
1182            <para>NS:NS-STRING</para>
1183          </refsect1>
1184
1185          <refsect1>
1186            <title>Initargs</title>
1187           
1188            <variablelist>
1189              <varlistentry>
1190                <term>:string</term>
1191               
1192                <listitem>
1193                  <para>
1194                    a Lisp string which is to be the content of
1195                    the newly-created ns-lisp-string.
1196                  </para>
1197                </listitem>
1198              </varlistentry>
1199            </variablelist>
1200          </refsect1>
1201
1202          <refsect1>
1203            <title>Description</title>
1204
1205            <para>
1206              This class
1207              implements the interface of an NSString, which means that it can
1208              be passed to any Cocoa or Core Foundation function which expects
1209              one.
1210            </para>
1211
1212            <para>
1213              The string itself is stored on the Lisp heap, which
1214              means that its memory management is automatic.  However, the
1215              ns-lisp-string object itself is a foreign
1216              object (that is, it has an objc metaclass), and resides on the
1217              foreign heap.  Therefore, it is necessary to explicitly free
1218              it, by sending a dealloc message.
1219            </para>
1220          </refsect1>
1221
1222          <refsect1>
1223            <title>Examples</title>
1224
1225            <para>
1226              You can create an ns-lisp-string with
1227              <function>make-instance</function>, just like
1228              any normal Lisp class:
1229            </para>
1230
1231            <programlisting format="linespecific"
1232>? (defvar *the-string*
1233          (make-instance 'ccl::ns-lisp-string
1234                         :string "Hello, Cocoa."))</programlisting>
1235           
1236            <para>
1237              When you are done with the string, you must explicitly
1238              deallocate it:
1239            </para>
1240
1241            <programlisting format="linespecific">? (ccl::send *the-string* 'dealloc)</programlisting>
1242
1243            <para>
1244              You may wish to use an <function>unwind-protect</function>
1245              form to ensure that this happens:
1246            </para>
1247
1248            <programlisting format="linespecific"
1249>(let (*the-string*)
1250  (unwind-protect (progn (setq *the-string*
1251                               (make-instance 'ccl::ns-lisp-string
1252                                              :string "Hello, Cocoa."))
1253                         (format t "~&amp;The string is ~D characters long.~%"
1254                                 (ccl::send *the-string* 'length)))
1255    (when *the-string*
1256      (ccl::send *the-string* 'dealloc))))</programlisting>
1257          </refsect1>
1258
1259          <refsect1>
1260            <title>Notes</title>
1261
1262            <para>
1263              Currently, ns-lisp-string is defined in
1264              the file ccl/examples/cocoa-backtrace.lisp, which is a
1265              rather awkward place.  It was probably not originally meant
1266              as a public utility at all.  It would be good if it were
1267              moved someplace else.  Use at your own risk.
1268            </para>
1269          </refsect1>
1270        </refentry>
1271    </sect1>
1272  </chapter>
Note: See TracBrowser for help on using the repository browser.