home *** CD-ROM | disk | FTP | other *** search
/ Celestin Apprentice 5 / Apprentice-Release5.iso / Source Code / Libraries / CW GUSI 1.6.4 / doc / pod / GUSI_Misc.pod < prev    next >
Encoding:
Text File  |  1995-04-20  |  8.6 KB  |  204 lines  |  [TEXT/CWIE]
  1. =head1 Miscellaneous
  2.  
  3. =head2 BSD memory routines
  4.  
  5. These are implemented as macros if you 
  6.  
  7.    #include <compat.h>
  8.  
  9. C<void bzero(void * from, int len)> zeroes 
  10. C<len> bytes, starting at 
  11. C<from>.
  12.  
  13. C<void bfill(void * from, int len, int x)> fills 
  14. C<len> bytes, starting at 
  15. C<from> with
  16. C<x>.
  17.  
  18. C<void bcopy(void * from, void * to, int len)> copies 
  19. C<len> bytes from 
  20. C<from> to
  21. C<to>.
  22.  
  23. C<int bcmp(void * s1, void * s2, int len)> compares 
  24. C<len> bytes at 
  25. C<s1> against
  26. C<len> bytes at 
  27. C<s2>, returning zero if the two areas are equal, nonzero otherwise.
  28.  
  29. =head2 Hooks
  30.  
  31. You can override some of GUSI's behaviour by providing hooks to GUSI. Note that these
  32. often get called from deep within GUSI, so be sure you understand what is required
  33. of a hook before overriding it.
  34.  
  35. GUSI hooks can be accessed with the following routines:
  36.  
  37.     typedef void (*GUSIHook)(void);
  38.     void GUSISetHook(GUSIHookCode code, GUSIHook hook);
  39.     GUSIHook GUSIGetHook(GUSIHookCode code);
  40.  
  41. Currently, two hooks are defined. The C<GUSI_SpinHook> is defined in the next section.
  42. The C<GUSI_ExecHook> is used by GUSI to decide whether a file or folder is to be 
  43. considered "executable" or not. The default hook considers all folders and all
  44. applications (i.e., files of type C<'APPL'> and C<'appe'> to be executable. To provide
  45. your own hook, call
  46.  
  47.     GUSISetHook(GUSI_ExecHook, (GUSIHook) my_exec_hook);
  48.  
  49. where C<my_exec_hook> is defined as
  50.  
  51.     Boolean my_exec_hook(const GUSIFileRef & ref);
  52.  
  53. The old value is available as:
  54.  
  55.     Boolean (*)(const GUSIFileRef & ref)GUSIgetHook(GUSI_ExecHook);
  56.  
  57. =head2 Blocking calls
  58.  
  59. Since the Macintosh doesn't have preemptive task switching, it
  60. is important that other applications get a chance to run during blocking calls. This
  61. section discusses the mechanism C<GUSI> uses for that purpose.
  62.  
  63. While a routine is waiting for a blocking call to terminate, it repeatedly calls a
  64. spin routine with the following parameters:
  65.  
  66.    typedef enum spin_msg
  67.    {
  68.       SP_MISC,          /* some weird thing, usually just return immediately if you get this */
  69.       SP_SELECT,        /* in a select call, passes ticks the program is prepared to wait */
  70.       SP_NAME,          /* getting a host by name */
  71.       SP_ADDR,          /* getting a host by address */
  72.       SP_STREAM_READ,   /* Stream read call */
  73.       SP_STREAM_WRITE,  /* Stream write call */
  74.       SP_DGRAM_READ,    /* Datagram read call */
  75.       SP_DGRAM_WRITE,   /* Datagram write call */
  76.       SP_SLEEP,         /* sleeping, passes ticks left to sleep */
  77.       SP_AUTO_SPIN      /* Automatically spinning, passes spin count */
  78.    } spin_msg;
  79.  
  80.    typedef int (*GUSISpinFn)(spin_msg msg, long param);
  81.  
  82. If the spin routine returns a nonzero value, the call is interrupted and 
  83. C<EINTR> returned. You can modify the spin routine with the following calls:
  84.  
  85.     GUSISetHook(GUSI_SpinHook, (GUSIHook) my_spin_hook);
  86.     (GUSISpinFn)GUSIGetHook(GUSI_SpinHook);
  87.  
  88. (For backward compatibility, GUSI also defines the equivalents:)
  89.  
  90.     int GUSISetSpin(GUSISpinFn routine);
  91.     GUSISpinFn GUSIGetSpin(void);
  92.  
  93. Often, however, the default spin routine will do what you want: It spins a
  94. cursor and occasionally calls C<GetNextEvent()> or C<WaitNextEvent()>. By default,
  95. only mouse down and suspend/resume events are handled, but you can change that
  96. by passing your own C<GUSIEvtTable> to C<GUSISetEvents()>.
  97.  
  98.    int GUSISetEvents(GUSIEvtTable table);
  99.    GUSIEvtHandler * GUSIGetEvents(void);
  100.  
  101. A C<GUSIEvtTable> is a table of C<GUSIEvtHandlers>, indexed by event code. Presence
  102. of a non-nil entry in the table will cause that event class to be allowed for
  103. C<GetNextEvent()> or C<WaitNextEvent()>. C<GUSI> for C<MPW C> and C<PPCC> includes
  104. one event table to be used with the C<SIOW> library.
  105.  
  106.    typedef void (*GUSIEvtHandler)(EventRecord * ev);
  107.    typedef GUSIEvtHandler GUSIEvtTable[24];
  108.  
  109.    extern GUSIEvtHandler   GUSISIOWEvents[];
  110.  
  111. C<GUSI> also supports three POSIX/BSD routines: C<alarm(unsigned sec)> will after 
  112. C<sec> seconds cancel the current call, raise C<SIGALRM>, and return C<EINTR>. 
  113. Note that the default handler for C<SIGALRM> terminates the program, so be sure 
  114. to install your own handler. C<alarm(0)> cancels an alarm and returns the remaining 
  115. seconds. As opposed to POSIX systems, the C<GUSI> version of C<alarm()> does not use
  116. real clock interrupts and merely interrupts during a blocking call.
  117.  
  118. C<sleep(unsigned sec)> sleeps for C<sec> seconds, and C<usleep(unsigned usec)> does
  119. the same for C<usec> micorseconds (rounded to 60ths of a tick).
  120.  
  121. =head2 Resources
  122.  
  123. A few C<GUSI> routines (currently primarily choose()) need resources
  124. to work correctly. These are added if you Rez your program with C<GUSI.r>. On 
  125. startup, C<GUSI> also looks for a I<preference> resource with type 
  126. C<'GUZI'> (the C<'Z'> actually must be a capital Sigma) and ID C<GUSIRsrcID>, 
  127. which is currently defined as follows:
  128.  
  129.    #ifndef GUSI_PREF_VERSION
  130.    #define GUSI_PREF_VERSION '0102'
  131.    #endif
  132.  
  133.    type 'GUZI' {
  134.       literal longint   text  =  'TEXT';  /* Type for creat'ed files             */
  135.       literal longint   mpw   =  'MPS ';  /* Creator for creat'ed files          */
  136.       byte     noAutoSpin, autoSpin;      /* Automatically spin cursor ?         */
  137.    #if GUSI_PREF_VERSION >= '0110'
  138.       boolean  useChdir, dontUseChdir;    /* Use chdir() ?                    */
  139.       boolean  approxStat, accurateStat;  /* statbuf.st_nlink = # of subdirectories ? */
  140.       boolean  noTCPDaemon, isTCPDaemon;  /* Inetd client ?                   */
  141.       boolean  noUDPDaemon, isUDPDaemon;
  142.    #if GUSI_PREF_VERSION >= '0150'
  143.       boolean  noConsole, hasConsole;     /* Are we providing our own dev:console ? */
  144.       fill     bit[3];
  145.    #else
  146.       fill     bit[4];
  147.    #endif
  148.       literal longint = GUSI_PREF_VERSION;
  149.    #if GUSI_PREF_VERSION >= '0120'
  150.       integer = @t$$@>Countof(SuffixArray);
  151.  
  152.       wide array SuffixArray {
  153.             literal longint;              /* Suffix of file */
  154.             literal longint;              /* Type for file */
  155.             literal longint;              /* Creator for file */
  156.       };
  157.    #endif
  158.    #endif
  159.    };
  160.  
  161. To keep backwards compatible, the preference version is included, and you are free to
  162. use whatever version of the preferences you want by defining C<GUSI_PREF_VERSION>.
  163.  
  164. The first two fields define the file type and creator, respectively, to be used 
  165. for files created by C<GUSI>. The type and creator of existing files will never
  166. be changed unless explicitely requested with fsetfileinfo(). The default is to
  167. create text files (type `TEXT') owned by the C<MPW Shell> (creator `MPS '). If you
  168. request a preference version of 1.2.0 and higher, you are also allowed to specify
  169. a list of suffixes that are given different types. An example of such a list would be:
  170.  
  171.     { 'SYM ', 'MPSY', 'sade'  }
  172.  
  173. The C<autoSpin> value, if nonzero, makes C<GUSI> call the spin routine for every
  174. call to C<read()>, C<write()>, C<send()>, or C<recv()>. This is useful for making 
  175. an I/O bound program MultiFinder friendly without having to insert explicit calls
  176. to C<SpinCursor()>. If you don't specify a preference resource, C<autoSpin> is assumed
  177. to be C<1>. You may specify arbitrary values greater than one to make your program
  178. even friendlier; note, however, that this will hurt performance.
  179.  
  180. The C<useChdir> flag tells C<GUSI> whether you change directories with the 
  181. toolbox calls C<PBSetVol()> or C<PBHSetVol()> or with the C<GUSI> call C<chdir()>.
  182. The current directory will start with the directory your application resides in 
  183. or the current C<MPW> directory, if you're running an C<MPW> tool.
  184. If C<useChdir> is specified, the current directory will only change with C<chdir()> 
  185. calls. If C<dontUseChdir> is specified, the current directory will change with 
  186. toolbox calls, until you call C<chdir()> the first time. This behaviour is more
  187. consistent with the standard C<MPW> library, but has IMHO no other redeeming
  188. value. If you don't specify a preference resource, C<useChdir> is assumed.
  189.  
  190. If C<approxStat> is specified, C<stat()> and C<lstat()> for directories return in
  191. C<st_nlink> the number of I<items> in the directory C<+ 2>. If C<accurateStat> is
  192. specified, they return the number of I<subdirectories> in the directory. The
  193. latter has probably the best chances of being compatible with some Unix software,
  194. but the former is often a sufficient upper bound, is much faster, and most programs
  195. don't care about this value anyway. If you don't specify a preference resource, 
  196. C<approxStat> is assumed.
  197.  
  198. The C<isTCPDaemon> and C<isUDPDaemon> flags turn C<GUSI> programs into clients
  199. for David Petersons C<inetd>, as discussed below. If you don't specify a preference
  200. resource, C<noTCPDaemon> and C<noUDPDaemon> are assumed.
  201.  
  202. The C<hasConsole> flag should be set if you are overriding the default "dev:console",
  203. as discussed below.
  204.