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

Last change on this file since 12918 was 12918, checked in by rme, 11 years ago

Document actual fixnum ranges (rather than using XXX and YYY).

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