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

Last change on this file since 8908 was 8908, checked in by mikel, 11 years ago

added discussion of objc:defmethod and made some edits of existing docs for define-objc-method

File size: 47.6 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
216        the 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
283        seem to be substantial improvements over previous behaviors (where,
284        for instance, a misspelled message name typically terminated the
285        application.)</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
308      in the ccl directory, to quickly start your program.</para>
309    <para>The OS may have already decided that &CCL;.app isn't a valid
310      executable bundle, and therefore won't let you double-click it.
311      If this happens to you, to force it to reconsider, just update the
312      last-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
317      image is dependent upon the <emphasis>exact</emphasis> versions of
318      the Cocoa libraries which were present when it was saved.
319      Specifically, the interface database is.  So, for example, an
320      application produced under OS X 10.3.5 will not work under
321      OS X 10.3.6.  This is inconvenient when you wish to distribute an
322      application 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
325      application bundles in a different way.  It is
326      available here, as part
327      of the "Clotho" project, and there is
328      here.</para>
329    <para>When an image which had contained ObjC classes (which are also
330      CLOS classes) is re-launched, those classes are "revived": all
331      preexisting classes have their addresses updated destructively, so that
332      existing subclass/superclass/metaclass relationships are maintained.
333      It's not possible (and may never be) to preserve foreign
334      instances across SAVE-APPLICATION. (It may be the case that NSArchiver
335      and 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_objc-defmethod">
948          <indexterm zone="m_objc-defmethod">
949            <primary>objc:defmethod</primary>
950          </indexterm>
951
952          <refnamediv>
953            <refname>objc:defmethod</refname>
954            <refpurpose></refpurpose>
955            <refclass>Macro</refclass>
956          </refnamediv>
957
958          <refsynopsisdiv>
959            <synopsis><function>objc:defmethod</function>
960              name-and-result-type ((receiver-arg-and-class) &rest;
961              other-args) &body; body</synopsis>
962          </refsynopsisdiv>
963
964          <refsect1>
965            <title>Arguments and Values</title>
966
967            <variablelist>
968
969              <varlistentry>
970                    <term>name-and-result-type</term>
971           
972                    <listitem>
973                      <para>either an Objective-C message name, for methods
974                that return a value of type <literal>:ID</literal>, or
975                a list containing an Objective-C message name and a
976                foreign type specifier for methods with a different
977                foreign result type.</para>
978                    </listitem>
979              </varlistentry>
980         
981              <varlistentry>
982                    <term>receiver-arg-and-class</term>
983           
984                    <listitem>
985                      <para>a two-element list whose first element is a
986                variable name and whose second element is the Lisp
987                name of an Objective-C class or metaclass.  The
988                receiver variable name can be any bindable lisp
989                variable name, but <literal>SELF</literal> might be a
990                reasonable choice.  The receiver variable is declared
991                to be "unsettable"; i.e., it is an error to try to
992                change the value of the receiver in the body of the
993                method definition.</para>
994                    </listitem>
995              </varlistentry>
996         
997              <varlistentry>
998                    <term>other-args</term>
999           
1000                    <listitem>
1001                      <para>either variable names (denoting parameters of
1002            type <literal>:ID</literal>) or 2-element lists whose
1003            first element is a variable name and whose second element
1004            is a foreign type specifier.</para>
1005                    </listitem>
1006              </varlistentry>
1007         
1008              </variablelist>
1009            </refsect1>
1010       
1011            <refsect1>
1012              <title>Description</title>
1013         
1014              <para>Defines an Objective-C-callable method which implements
1015                the specified message selector for instances of the existing
1016                named Objective-C class.</para>
1017
1018          <para>For a detailed description of the features and
1019          restrictions of the <literal>OBJC:DEFMETHOD</literal> macro,
1020          see the
1021          section <link linkend="anchor_Using-objc-defmethod">Using <literal>objc:defmethod</literal></link>.</para>
1022            </refsect1>
1023          </refentry>
1024     
1025          <refentry id="m_define-objc-method">
1026            <indexterm zone="m_define-objc-method">
1027              <primary>define-objc-method</primary>
1028            </indexterm>
1029
1030            <refnamediv>
1031              <refname>CCL::DEFINE-OBJC-METHOD</refname>
1032              <refpurpose></refpurpose>
1033              <refclass>Macro</refclass>
1034            </refnamediv>
1035
1036            <refsynopsisdiv>
1037              <synopsis><function>define-objc-method</function>
1038                (selector class-name) &body; body</synopsis>
1039            </refsynopsisdiv>
1040
1041            <refsect1>
1042              <title>Arguments and Values</title>
1043
1044              <variablelist>
1045                <varlistentry>
1046                      <term>selector</term>
1047
1048                      <listitem>
1049                        <para>either a string which represents the name of the
1050                          selector or a list which describ+es the method's return
1051                          type, selector components, and argument types (see below.)
1052                          If the first form is used, then the first form in the body
1053                          must be a list which describes the selector's argument
1054                          types and return value type, as per DEFCALLBACK.</para>
1055                      </listitem>
1056                </varlistentry>
1057
1058                <varlistentry>
1059                      <term>class-name</term>
1060
1061                      <listitem>
1062                        <para>either a string which names an existing ObjC class
1063                          name or a list symbol which can map to such a string via the
1064                          standard name-mapping conventions for class names. (Note
1065                          that the "canonical" lisp class name is such a
1066                          symbol)</para>
1067                      </listitem>
1068                </varlistentry>
1069              </variablelist>
1070            </refsect1>
1071
1072            <refsect1>
1073              <title>Description</title>
1074
1075              <para>Defines an ObjC-callable method which implements the
1076                specified message selector for instances of the existing ObjC
1077                class class-name.</para>
1078            </refsect1>
1079          </refentry>
1080
1081          <refentry id="m_define-objc-class-method">
1082            <indexterm zone="m_define-objc-class-method">
1083              <primary>define-objc-class-method</primary>
1084            </indexterm>
1085
1086            <refnamediv>
1087              <refname>CCL::DEFINE-OBJC-CLASS-METHOD</refname>
1088              <refpurpose></refpurpose>
1089              <refclass>Macro</refclass>
1090            </refnamediv>
1091
1092            <refsynopsisdiv>
1093              <synopsis><function>define-objc-class-method</function>
1094                (selector class-name) &body; body</synopsis>
1095            </refsynopsisdiv>
1096
1097            <refsect1>
1098              <title>Arguments and Values</title>
1099
1100              <para>As per DEFINE-OBJC-METHOD</para>
1101            </refsect1>
1102
1103            <refsect1>
1104              <title>Description</title>
1105
1106              <para>Like DEFINE-OBJC-METHOD, only used to define methods on the
1107                <emphasis>class</emphasis> named by class-name and on its
1108                subclasses.</para>
1109
1110              <para>For both DEFINE-OBJC-METHOD and DEFINE-OBJC-CLASS-METHOD, the
1111                "selector" argument can be a list whose first element is a
1112                foreign type specifier for the method's return value type and whose
1113                subsequent elements are either:</para>
1114
1115              <itemizedlist>
1116                <listitem>
1117                      <para>a non-keyword symbol, which can be mapped to a selector string
1118                        for a parameterless method according to the standard name-mapping
1119                        conventions for method selectors.</para>
1120                </listitem>
1121               
1122                <listitem>
1123                      <para>a list of alternating keywords and variable/type specifiers,
1124                        where the set of keywords can be mapped to a selector string for a
1125                        parameteriezed method according to the standard name-mapping
1126                        conventions for method selectors and each variable/type-specifier is
1127                        either a variable name (denoting a value of type :ID) or a list whose
1128                        CAR is a variable name and whose CADR is the corresponding
1129                        argument's foreign type specifier.</para>
1130                </listitem>
1131              </itemizedlist>
1132            </refsect1>
1133          </refentry>
1134
1135          <refentry id="v_alternate-line-terminator">
1136            <indexterm zone="v_alternate-line-terminator">
1137              <primary>*alternate-line-terminator*</primary>
1138            </indexterm>
1139
1140            <refnamediv>
1141              <refname>CCL:*ALTERNATE-LINE-TERMINATOR*</refname>
1142              <refpurpose></refpurpose>
1143              <refclass>Variable</refclass>
1144            </refnamediv>
1145
1146            <refsect1>
1147              <title>Description</title>
1148
1149              <para>This variable is currently only used by the standard reader macro
1150                function for #\; (single-line comments); that function reads successive
1151                characters until EOF, a #\NewLine is read, or a character EQL to the
1152                value of *alternate-line-terminator* is read. In &CCL; for Darwin, the
1153                value of this variable is initially #\Return ; in &CCL; for LinuxPPC,
1154                it&#39;s initially NIL.</para>
1155             
1156              <para>Their default treatment by the #\; reader macro is the primary way
1157                in which #\Return and #\Linefeed differ syntactally; by extending the
1158                #\; reader macro to (conditionally) treat #\Return as a
1159                comment-terminator, that distinction is eliminated. This seems to make
1160                LOAD and COMPILE-FILE insensitive to line-termination issues in many
1161                cases. It could fail in the (hopefully rare) case where a LF-terminated
1162                (Unix) text file contains embedded #\Return characters, and this
1163                mechanism isn&#39;t adequate to handle cases where newlines are embedded
1164                in string constants or other tokens (and presumably should be translated
1165                from an external convention to the external one) : it doesn&#39;t change
1166                what READ-CHAR or READ-LINE &#34;see&#34;, and that may be necessary to
1167                handle some more complicated cases.</para>
1168            </refsect1>
1169          </refentry>
1170
1171          <refentry id="k_external-format">
1172            <indexterm zone="k_external-format">
1173              <primary>:external-format</primary>
1174            </indexterm>
1175
1176            <refnamediv>
1177              <refname>:EXTERNAL-FORMAT</refname>
1178              <refpurpose></refpurpose>
1179              <refclass>Keyword Argument</refclass>
1180            </refnamediv>
1181
1182            <refsect1>
1183              <title>Description</title>
1184
1185              <para>Per ANSI CL, &CCL; supports the :EXTERNAL-FORMAT keyword
1186                argument to the functions OPEN, LOAD, and COMPILE-FILE. This argument is
1187                intended to provide a standard way of providing implementation-dependent
1188                information about the format of files opened with an element-type of
1189                CHARACTER. This argument can meaningfully take on the values :DEFAULT
1190                (the default), :MACOS, :UNIX, or :INFERRED in &CCL;.</para>
1191             
1192              <para>When defaulted to or specified as :DEFAULT, the format of the file
1193                stream is determined by the value of the variable
1194                CCL:*DEFAULT-EXTERNAL-FORMAT*. See below.</para>
1195             
1196              <para>When specified as :UNIX, all characters are read from and written
1197                to files verbatim.</para>
1198             
1199              <para>When specified as :MACOS, all #\Return characters read from the
1200                file are immediately translated to #\Linefeed (#\Newline); all #\Newline
1201                (#\Linefeed) characters are written externally as #\Return characters.</para>
1202             
1203              <para>When specified as :INFERRED and the file is open for input, the
1204                first bufferful of input data is examined; if a #\Return character
1205                appears in the buffer before the first #\Linefeed, the file stream&#39;s
1206                external-format is set to :MACOS; otherwise, it is set to :UNIX.</para>
1207             
1208              <para>All other values of :EXTERNAL-FORMAT - and any combinations that
1209                don&#39;t make sense, such as trying to infer the format of a
1210                newly-created output file stream - are treated as if :UNIX was
1211                specified. As mentioned above, the :EXTERNAL-FORMAT argument doesn&#39;t
1212                apply to binary file streams.</para>
1213             
1214              <para>The translation performed when :MACOS is specified or inferred has
1215                a somewhat greater chance of doing the right thing than the
1216                *alternate-line-terminator* mechanism does; it probably has a somewhat
1217                greater chance of doing the wrong thing, as well.</para>
1218            </refsect1>
1219          </refentry>
1220
1221          <refentry id="v_default-external-format">
1222            <indexterm zone="v_default-external-format">
1223              <primary>*default-external-format*</primary>
1224            </indexterm>
1225           
1226            <refnamediv>
1227              <refname>CCL:*DEFAULT-EXTERNAL-FORMAT*</refname>
1228              <refpurpose></refpurpose>
1229              <refclass>Variable</refclass>
1230            </refnamediv>
1231
1232            <refsect1>
1233              <title>Description</title>
1234
1235              <para>The value of this variable is used when :EXTERNAL-FORMAT is
1236                unspecified or specified as :DEFAULT. It can meaningfully be given any
1237                of the values :UNIX, :MACOS, or :INFERRED, each of which is interpreted
1238                as described above.</para>
1239             
1240              <para>Because there&#39;s some risk that unsolicited newline translation
1241                could have undesirable consequences, the initial value of this variable
1242                in &CCL; is :UNIX.</para>
1243            </refsect1>
1244          </refentry>
1245
1246          <refentry id="c_ns-lisp-string">
1247            <indexterm zone="c_ns-lisp-string">
1248              <primary>ns-lisp-string</primary>
1249            </indexterm>
1250
1251            <refnamediv>
1252              <refname>CCL::NS-LISP-STRING</refname>
1253              <refpurpose></refpurpose>
1254              <refclass>Class</refclass>
1255            </refnamediv>
1256
1257            <refsect1>
1258              <title>Superclasses</title>
1259
1260              <para>NS:NS-STRING</para>
1261            </refsect1>
1262
1263            <refsect1>
1264              <title>Initargs</title>
1265             
1266              <variablelist>
1267                <varlistentry>
1268                      <term>:string</term>
1269                     
1270                      <listitem>
1271                        <para>
1272                          a Lisp string which is to be the content of
1273                          the newly-created ns-lisp-string.
1274                        </para>
1275                      </listitem>
1276                </varlistentry>
1277              </variablelist>
1278            </refsect1>
1279
1280            <refsect1>
1281              <title>Description</title>
1282
1283              <para>
1284                This class
1285                implements the interface of an NSString, which means that it can
1286                be passed to any Cocoa or Core Foundation function which expects
1287                one.
1288              </para>
1289
1290              <para>
1291                The string itself is stored on the Lisp heap, which
1292                means that its memory management is automatic.  However, the
1293                ns-lisp-string object itself is a foreign
1294                object (that is, it has an objc metaclass), and resides on the
1295                foreign heap.  Therefore, it is necessary to explicitly free
1296                it, by sending a dealloc message.
1297              </para>
1298            </refsect1>
1299
1300            <refsect1>
1301              <title>Examples</title>
1302
1303              <para>
1304                You can create an ns-lisp-string with
1305                <function>make-instance</function>, just like
1306                any normal Lisp class:
1307              </para>
1308
1309              <programlisting format="linespecific"
1310>? (defvar *the-string*
1311     (make-instance 'ccl::ns-lisp-string
1312                    :string "Hello, Cocoa."))
1313</programlisting>
1314             
1315              <para>
1316                When you are done with the string, you must explicitly
1317                deallocate it:
1318              </para>
1319
1320              <programlisting format="linespecific">? (ccl::send *the-string* 'dealloc)</programlisting>
1321
1322              <para>
1323                You may wish to use an <function>unwind-protect</function>
1324                form to ensure that this happens:
1325              </para>
1326
1327              <programlisting format="linespecific"
1328>(let (*the-string*)
1329  (unwind-protect (progn (setq *the-string*
1330                               (make-instance 'ccl::ns-lisp-string
1331                                              :string "Hello, Cocoa."))
1332                         (format t "~&amp;The string is ~D characters long.~%"
1333                                 (ccl::send *the-string* 'length)))
1334    (when *the-string*
1335      (ccl::send *the-string* 'dealloc))))
1336</programlisting>
1337
1338            </refsect1>
1339
1340            <refsect1>
1341              <title>Notes</title>
1342
1343              <para>
1344                Currently, ns-lisp-string is defined in
1345                the file ccl/examples/cocoa-backtrace.lisp, which is a
1346                rather awkward place.  It was probably not originally meant
1347                as a public utility at all.  It would be good if it were
1348                moved someplace else.  Use at your own risk.
1349              </para>
1350            </refsect1>
1351          </refentry>
1352    </sect1>
1353  </chapter>
Note: See TracBrowser for help on using the repository browser.