home *** CD-ROM | disk | FTP | other *** search
/ GEMini Atari / GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso / zip / program / lynxlib.zoo / lynxlib.doc < prev    next >
Text File  |  1991-01-26  |  37KB  |  982 lines
  1. Documentation to LynxLib version .9 beta test.
  2. December 22, 1990
  3.  
  4. The LynxLib library, except for portions created by others, is
  5. property of Robert Fischer and is Copyright 1990 by Robert Fischer.
  6. LynxLib is distributed in the hope that it will be useful, but WITHOUT
  7. ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
  8. FITNESS FOR A PARTICULAR PURPOSE.  In no case will the author be
  9. liable for any damages incurred by using LynxLib. 
  10.  
  11.     To contact the author, call or write:
  12.         Robert Fischer
  13.         80 Killdeer Road
  14.         Hamden, CT    06517
  15.         (203) 288-9599
  16.  
  17. LynxLib is subject to the following conditions:
  18.  
  19. * You may distribute LynxLib to anyone you wish, as long as you make
  20. no money off of it and it's an original, unmodified version of
  21. LynxLib.  In distributing it, you may distribute object code, but you
  22. _must_ distribute source code along with it.  You may only change
  23. LynxLib enough to work with your specific compiler, and you must use
  24. #ifdef statements, so that if no compiler name is defined, it will
  25. compile under Mark Williams C.  If you find some section of code which
  26. doesn't work, for example, under Megamax C, you would do the
  27. following:
  28.  
  29.     #ifdef MEGAMAX
  30.         ~~~~ your new code for MEGAMAX C ~~~~~~~~
  31.     #else
  32.         ~~~~~ the old code for Mark Williams C ~~~~~~~~
  33.     #endif
  34.  
  35. * If you wish to distribute a modified version of the source code,
  36. distribute in a way so that the user can also have the original
  37. version.  For example, if you change the function natoi() in the file
  38. ATOI.C, you must distribute the original ATOI.C along with your
  39. modified ATOI.C.  Any additions or changes you make to LynxLib must be
  40. labelled as such.  You may not remove code from LynxLib. 
  41.  
  42. * Whenever you distribute a modified version, you must send it to the
  43. me (Robert Fischer) with a short description of what your improvements
  44. are, and I will incorporate your improvements, if I feel that they
  45. improve LynxLib, in the next version of LynxLib.  As long as your
  46. improvements don't make LynxLib incompatible with older versions, they
  47. will probably be included.  I reserve the right to not incorporate
  48. your change, although I will try to incorporate changes which add more
  49. features and make LynxLib easier to use. 
  50.  
  51. * If I decide to incorporate your change, it remains yours, but you
  52. given up rights to withold copies of your modification or charge money
  53. for it.  It _will_ be distributed to the world at that point.  It's
  54. your responsibility that the source code you give me is actually yours
  55. to give to me.  For example, I don't want to receive source code
  56. ripped off of Microsoft, use it, and then get Microsoft on my back... 
  57.  
  58. * If I incorporate your changes, I'll include your name at the point
  59. of modification in LynxLib.
  60.  
  61. * If I decide not to incorporate your changes, I will write a letter
  62. to you stating as such within 15 days of receiving them.  (If you
  63. leave no way to contact you, the source code becomes mine to do
  64. whatever I want with.) They then remain yours, to do whatever you wish
  65. with. 
  66.  
  67. Following is brief documentation on all supported user functions in
  68. LynxLib. 
  69.  
  70. -----------------------------------------------------------------
  71.  
  72. ALLOCA.C: Allocates memory on the stack
  73.     alloca -- (mostly) portable public-domain implementation -- D A Gwyn
  74.  
  75.     This implementation of the PWB library alloca() function,
  76.     which is used to allocate space off the run-time stack so
  77.     that it is automatically reclaimed upon procedure exit, 
  78.     was inspired by discussions with J. Q. Johnson of Cornell.
  79.  
  80.     alloca( size ) returns a pointer to at least `size' bytes of
  81.     storage which will be automatically reclaimed upon exit from
  82.     the procedure that called alloca().  Originally, this space
  83.     was supposed to be taken from the current stack frame of the
  84.     caller, but that method cannot be made to work for some
  85.     implementations of C, for example under Gould's UTX/32.
  86.  
  87.     As a special case, alloca(0) reclaims storage without
  88.     allocating any.  It is a good idea to use alloca(0) in
  89.     your main control loop, etc. to force garbage collection.
  90.  
  91. alloca (size)           /* returns pointer to storage */
  92.      unsigned   size;       /* # bytes to allocate */
  93.  
  94. Include files: ALLOCA.H
  95. See also: none
  96.  
  97. /* ----------------------------------------------------------- */
  98. ATOI.C: Converts between integers and strings
  99.  
  100. BOOLEAN natoi(stringg, base, result)
  101. char *stringg;
  102. int base;
  103. int *result;
  104. /* Returning a FALSE indicates an error. */
  105. Converts an int to a string, in any base
  106.  
  107. BOOLEAN natol(stringg, base, result)
  108. char *stringg;
  109. int base;
  110. long *result;
  111. /* Returning a FALSE indicates an error. */
  112. Converts a long to a string, in any base
  113.  
  114. /* Converts integer to string of specified length.        */
  115. /* Fills with leading zeros.                      */
  116. fitoa(val, len, base, s)
  117. int val, len, base;
  118. char *s;
  119.  
  120. /* Converts unsigned integer to string of specified length.       */
  121. /* Fills with leading zeros.                      */
  122. ufitoa(val, len, base, s)
  123. unsigned val, len, base;
  124. char *s;
  125.  
  126. char *catoi(stringg, base, result)
  127. /* Converts a string to an integer and
  128.     returns *character of 1st non-numeral */
  129. char *stringg;
  130. int base;
  131. int *result;
  132. /* If no number found, doesn't destroy the previous contents of *result */
  133. This returns the address of the first non-numeral in the string
  134. stringg.  That's useful if you need to parse a string filled with
  135. numbers and other things.
  136.  
  137. Include files: ATOI.H
  138. See also: none
  139. -----------------------------------------------------------------
  140. CLOCK.S: Read the clock, and make a delay
  141.  
  142. _read_clock:
  143. wait(delay) int delay;
  144. Waits 'delay'/200 seconds
  145.  
  146. -----------------------------------------------------------------
  147. CLOCK.S: Read the clock, and make a delay
  148.  
  149. _read_clock:
  150. wait(delay) int delay;
  151. Waits 'delay'/200 seconds
  152. -----------------------------------------------------------------
  153. COLSW.C: Switch the mapping of the colors in a picture file.  This is
  154. useful, for example, if you want to make pretty colors which rotate
  155. nicely in NEOChrome, from a file with mixed-up colors. 
  156.  
  157. For example, if the old picture had red as color 5 and green as color
  158. 3, you could change it so that green is color 5 and red is color 3.
  159.  
  160. colsw(pic, pal, newpal)     /* Does the above operation on a picture */
  161. /* Takes a low-res picture, switches around its colors, but does not */
  162. /* change its appearance. */
  163. BYTE *pic;                  /* The picture & palette to do this to */
  164. PALETTE pal;
  165. PAL_TRANS newpal;           /* The palette translation table */
  166.  
  167. A PAL_TRANS is a translation table for colsw().  In the above routine,
  168. then pal[newpal[n]] = pal[n].  In other words, color in position n is
  169. transferred to position newpal[n]. 
  170.  
  171. typedef BYTE PAL_TRANS[16];
  172.  
  173. Include files: TOS.H, COLSW.H
  174. See also: PICTURE.C (to load and save the picture)
  175. -----------------------------------------------------------------
  176.  
  177. DATECONV.C: Convert between the date formats.  This is flexible, letting
  178. you convert between a myraid of date formats. 
  179.  
  180. dtoa(date, divide, order, s)    /* Date to string */
  181. date_rec date;      /* System-format date */
  182. char divide;        /* Divider to use ('/', '-', or '\0' if none to be used) */
  183. int order;          /* Bit string specifying what should be in each field */
  184.     /* It's twelve bits long, and bits are in groups of four.  Each group */
  185.     /* holds either a 0 (DAY), 1 (MONTH) or 2 (YEAR).  So 0x102 means MMDDYY. */
  186. char *s;            /* String to put output in */
  187.  
  188. ttoa(time, divide, showsec, s)  /* Time to string */
  189. time_rec time;      /* Time to convert */
  190. char divide;        /* Divider character, NIL if none */
  191. BOOLEAN showsec;    /* Convert seconds too? */
  192. char *s;            /* Output string */
  193.  
  194. BOOLEAN atot(t, s)
  195. /* Returns FALSE if no time found, or on error */
  196. time_rec *t;
  197. register unsigned char *s;
  198.  
  199. Converts string to time.  Handles 12/24 hr, with or without seconds,
  200. with or without dividers between the fields.  Without dividers, all
  201. fields must be two characters long. 
  202.  
  203. BOOLEAN atod(d, order, s)
  204. /* Returns FALSE if no date found, or on error */
  205. date_rec *d;
  206. int order;          /* Order expected, as with dtoa */
  207. register unsigned char *s;
  208.  
  209. Converts string to date.  Handles a variety of formats, with or
  210. without dividers.  Expects the month, day and year in the order
  211. specified by order. 
  212.  
  213. BOOLEAN atotd(td, order, s)
  214. /* Converts a date&time of the form "DATE TIME" to GEMDOS_TD_REC */
  215. GEMDOS_TD_REC *td;
  216. int order;          /* Order for date */
  217. char *s;
  218.  
  219. This combines the above two, and works on strings such as "12/3/90
  220. 0923", meaning December 3 (or March 12, depending on order), 9:23 AM.
  221.  
  222. BOOLEAN cmp_date(adate, atime, bdate, btime)
  223. /* Returns TRUE if the adtm > bdtm */
  224. date_rec adate;
  225. time_rec atime;
  226. date_rec bdate;
  227. time_rec btime;
  228.  
  229. Include files: TOS.H DATECONV.H
  230. See also: 
  231. -----------------------------------------------------------------
  232. EXINPUT.C
  233.  
  234. int fsel_exinput(path, file, button, label)
  235. /* Binding to the new AES call, as found in the Rainbow TOS */
  236. /* developer's release notes, August 7, 1989, page 26 */
  237. int *path, *file;
  238. int *button;
  239. char *label;
  240.  
  241. This works just like fsel_input, only it allows a message in the
  242. string label to appear in the file selector.  It checks the TOS
  243. version number, and if it's before TOS 1.4, fsel_exinput uses its own
  244. message-display system for the file selector.
  245.  
  246. Include files: 
  247. See also: 
  248. -----------------------------------------------------------------
  249.  
  250. GDOS.S
  251. BOOLEAN gdos_there()
  252.  
  253. Tests if GDOS is there, as given by ATARI.  Returns TRUE if it is,
  254. FALSE if it isn't.
  255.  
  256. Include files: 
  257. See also: 
  258. -----------------------------------------------------------------
  259. GEMVAR.C
  260.  
  261. Variables needed for VDI, AES.  That way, you don't need to define
  262. intin[], ptsin[], etc. all the time in your program.  Simply include
  263. gemvar.o in your linking.
  264.  
  265. Include files: 
  266. See also: 
  267. -----------------------------------------------------------------
  268. GETCOOKI.C
  269. /* getcookie(): C procedure to find cookies and values
  270. This is taken from Atari's STE Developer Notes, January 12, 1990.
  271.  
  272. BOOLEAN getcookie(cookie, p_value)
  273. LONG cookie; LONG *p_value;
  274.  
  275. Returns FALSE if 'cookie' is not found in the cookie jar.  If the
  276. cookie is found, it returns TRUE and places the cookie's value into
  277. *p_value.  If p_value == NULL, it doesn't put the value anywhere, but
  278. simply tells you whether the cookie is there.
  279.  
  280. Include files: GETCOOKI.H
  281. See also: 
  282. -----------------------------------------------------------------
  283. MAXMIN.C
  284.  
  285. max(a, b) int a, b;
  286. min(a, b) int a, b;
  287.  
  288. Simple routines to return the maximum and minimum of a and b.
  289.  
  290. Include files: 
  291. See also: 
  292. -----------------------------------------------------------------
  293. MYGEM.C: A bunch of useful routines for use with AES
  294.  
  295. gem_ok(s)   /* Puts up a GEM OK box */
  296. char *s;
  297. Puts up an alert box with the message s in it and an OK button.
  298.  
  299. gem_err(s)  /* Puts up a GEM error box */
  300. char *s;
  301. Similar to gem_ok(), except it puts up an 'Abort' button.
  302.  
  303. dial_form(d, n) /* Does a form_dial on box d, with mode n */
  304. register OBJECT *d;
  305. int n;
  306. Performs a dial_form() call with mode n on the area covered by box d.
  307. Useful for making growing/shrinking boxes easily, drawing dialog boxes.
  308.  
  309. draw_box(d)     /* Draws a dialog box */
  310. OBJECT *d;
  311. Draws the entire dialog box d.  Very easy to use.
  312.  
  313. map_obtree(d, this, last, routine)
  314. /* General object tree walking routine.  Applies an operation
  315.     to every node in the tree. This routine was gotton out of
  316.     issue 5 of PROGEM, by Tim Oren. */
  317. OBJECT *d;      /* Tree to walk */
  318. int this;       /* Node to start at. */
  319. int last;       /* Node to stop at (This node won't be affected) */
  320. int (*routine)();   /* Routine to apply to every node of tree */
  321.     /* routine takes the arguments: routine(d, obj)
  322.             OBJECT *d;  (* Address of object tree *)
  323.             int obj;    (* Object in object tree *)
  324.  
  325.         If your routine wants no more walking on the subtree, it
  326.         returns TRUE. Normaly, it should return FALSE. 
  327.  
  328. set_rchecked(d, obj, box, obox, redraw, checked)
  329. /* Sets a little box to checked or non-checked, and makes an object
  330.    subtree disappear, according to checked */
  331. OBJECT *d;      /* The object tree to work in */
  332. int obj;        /* Index into the tree */
  333. int box;        /* object to set or unset HIDETREE */
  334. int obox;       /* object to redraw, to see effects on box */
  335. BOOLEAN redraw; /* Redraw obox? */
  336. BOOLEAN checked;    /* Boolean value representing checkedness of obj when */
  337.     /* flip_checked was called.  flip_checked() flips this value. */
  338.     /* TRUE means the box is checked, FALSE means it is unchecked. */
  339.  
  340. This is a little complicated.  Often, you want to make a box which the
  341. user is allowed to check or uncheck.  When the user checks it, you
  342. want some other part of the object tree to disappear.  This command
  343. allows that.  You call it with obj (the box to check or uncheck), box
  344. (the object to hide) and obox (an object around box).  obox is needed
  345. because simply redrawing box after you've hidden it won't do anything.
  346. You must have another object containing box which you need to redraw.
  347.  
  348. center_form(d)
  349. OBJECT *d;
  350. Centers a dialog box.  Very easy.
  351.  
  352. Routines found in MYGEM.H:
  353.  
  354. #define undraw_box(d) dial_form(d, FMD_FINISH);
  355. Erases the box d from the screen.
  356.  
  357. #define draw_obj(d, obj) objc_draw(d, obj, 256, 0, 0, 0, 0);
  358. Draws an object with all its subtrees.
  359.  
  360. Include files: NOBDEFS.H, GEMDEFS.H, MYGEM.H
  361. See also: 
  362. -----------------------------------------------------------------
  363. PATHNAME.C: Handles pathnames in fancy ways
  364.  
  365. add_slash(name)
  366. char *name;
  367. Adds a back-slash to the end of name if there isn't already one.
  368.  
  369. trim_slash(name)
  370. char *name;
  371. Takes a back-slash off the end of name if there's one.
  372.  
  373. ppath(path, drvltr, dir, leaf)
  374. /* Parses a path name and returns its component parts   */
  375. char *path;     /* Input path name                      */
  376. char *drvltr;   /* Output: drive letter of path         */
  377.                 /* 0 = default, 'A' = drive A, ...      */
  378. char *dir;      /* Directory part of name:              */
  379.     /* '.\'     - default directory                     */
  380.     /* '\'      - root directory                        */
  381.     /* '.\xxx\' - subfolder of default dir              */
  382.     /* '\xxx\'  - subfolder of root                     */
  383. char *leaf;     /* Leaf name or wildcard pattern        */
  384.  
  385. resolve_pname(ipath, dflt)
  386. /* Converts path to fully specified form, supplying current default     */
  387. /*     drive and directory.                                             */
  388. /* Eliminates all occurrences of '.' and '..'                           */
  389. /* BUGS: The default directory given in dflt is used as the default
  390.          for ALL drives.  For example, if ipath=c:x and dflt=e:\r\,
  391.          then ipath is resolved to c:\r\x                               */
  392. char *ipath;    /* Path name to be resolved.  Output returned here, too */
  393. char *dflt;     /* Default pathname to use for ambiguous things. */
  394.     /* If defalt is '', use GEMDOS's defaults */
  395.  
  396. resolve_dname(idir, dflt)
  397. /* Resolves a directory name */
  398. char *idir;
  399. char *dflt;
  400.  
  401. get_curdir(pname)   /* gets the current directory */
  402. char *pname;
  403. The same as pwd in the UN*X shell.
  404.  
  405. trim_leaf(pname)    /* Removes the leaf from a name */
  406. /* E:\C turnes to E:\, E:\C\ turns to E:\C\ */
  407. register char *pname;
  408.  
  409. BOOLEAN g_file_attrib(name, modebits, td, size)
  410. /* Gets the file attributes according to directory */
  411. char *name;         /* name of file */
  412. WORD *modebits;     /* File's modebits */
  413. GEMDOS_TD_REC *td;  /* Files date and time */
  414. long *size;         /* Filesize */
  415. Given name, this routine fills in the rest of the variables.
  416.  
  417. BOOLEAN s_file_attrib(name, modebits, td)
  418. char *name;
  419. WORD modebits;
  420. GEMDOS_TD_REC td;
  421. The complement to g_file_attrib
  422.  
  423. BOOLEAN cd(d, odrive, opath)
  424. /* Changes current directory to dir.  Returns the previous default
  425. drive in odrive and the previous default path on the drive specified
  426. in d in opath.  Returns TRUE on success */
  427. char *d;
  428. int *odrive;
  429. char *opath;
  430.  
  431. BOOLEAN existd(d)       /* Sees if a directory exists */
  432. char *d;
  433. {
  434. fle_name defpath;   /* Saved default path */
  435. int defdrive;       /* Saved default drive */
  436. BOOLEAN ret;
  437.  
  438. BOOLEAN create_dir(d)   /* Creates a directory if it doesn't already exist */
  439. /* d may be a file-name.  Then the dir. of that name will be created */
  440. char *d;
  441. For example, create_dir("c:\xxx\yyy\zzz\file") on an empty disk C:\
  442. will create the directories c:\xxx, c:\xxx\yyy and then
  443. c:\xxx\yyy\zzz, ready for the file c:\xxx\yyy\zzz\file to be put into.
  444.  
  445. pleaf(leaf, root, ext)
  446. /* Parses a leaf into a root and extender */
  447. char *leaf, *root, *ext;
  448. Example.  Changes the leaf "FILE.XXX" into root "FILE" and ext "XXX"
  449.  
  450. Include files: 
  451. See also: 
  452. -----------------------------------------------------------------
  453. PEEKPOKE.C: Pretty wimpy.  Just one routine to poke values in
  454. byte-reversed form, for messing with boot sectors and such.
  455.  
  456. poke_ibm(addr, val)
  457. /* Byte-reverses val, and puts it into address addr, even an odd address */
  458. BYTE *addr;
  459. WORD val;
  460.  
  461. Include files: See also:
  462. -----------------------------------------------------------------
  463. PICTURE.C: Loads, converts, displays and saves pictures between many
  464. different formats: NEOchrome, DEGAS (not DEGAS compressed), SPC, SPU
  465. (Spectrum), plain (32000 bytes of data without color information),
  466. TINY (although not all TINY files work for some reason), and even
  467. DOODLE (hey C-64 fans, now you can read your old DOODLE pictures).
  468. Two experimental formats SPLAY and COMPRESS were taken out because
  469. they never really worked.  You can easily add your own format.  The
  470. structure pic_rec contains information about a picture in a standard
  471. form -- the palette, the bitmap, etc.  You need not worry about it.
  472. To load a picture, you use load_pic().  So display it, you use
  473. switch_pic() and then switch_norm() to undisplay it.  To save it
  474. (currently only as a NEO file), use save_neo().  To convert between
  475. resolutions, use change_res(), but currently it only converts from
  476. low-res to high-res.  A lot could be added to PICTURE.C
  477.  
  478. BOOLEAN load_pic(pic, name) /* Loads a picture from disk */
  479. register pic_rec *pic;  /* The place to load it to */
  480. char *name;             /* The name of the picture to load */
  481. /* Returns TRUE if the picture loaded OK */
  482.  
  483. switch_pic(pic) /* Switches screen to the specified picture */
  484. register pic_rec *pic;  /* The picture to switch to */
  485.  
  486. switch_norm(pic)    /* Switches back to the normal screen */
  487. register pic_rec *pic;  /* The picture to switch from */
  488.  
  489. BOOLEAN save_neo(pic, name)
  490. register pic_rec *pic;  /* The place to load it to */
  491. char *name;             /* The name of the picture to load */
  492. /* Returns TRUE if the picture saved OK */
  493.  
  494. BOOLEAN change_res(pic, dest_res)
  495. /* Converts a picture from its current resolution to the destination res */
  496. /* Currently, only converts low to high */
  497. pic_rec *pic;   /* Picture to convert */
  498. int dest_res;   /* Destination resolution */
  499.  
  500. Include files: PICTURE.H
  501.  
  502. See also: Coroutines and virtual files.  PICTURE.C uses them, although
  503. you don't have to know about them to use PICTURE.C
  504.  
  505. -----------------------------------------------------------------
  506. SETCOOKI.C: Put a cookie in the cookie jar, and return the cookie
  507. made.  If the cookie jar is full, setcookie() must allocate a new
  508. cookie jar.  To allow flexible memory allocation (for example, you
  509. might want to allocate permenant memory using PMalloc() in TRICKS.C),
  510. you can tell setcookie() which memory allocator to use, as a routine
  511. which takes a long telling the number of bytes to allocate, and
  512. returns a 0L if it couldn't allocate those bytes, or the address
  513. otherwise.  setcookie() uses the standard GEMDOS Malloc() if you give
  514. it a NULL. 
  515.  
  516. setcookie(cook, val, mem_alloc)
  517. LONG cook;          /* Cookie to set */
  518. LONG val;           /* Value of cookie */
  519. charpfunc *mem_alloc;   /* Memory allocator, if needed */
  520.     /* If NULL, Malloc is used */
  521.  
  522. Include files:
  523. See also: 
  524. -----------------------------------------------------------------
  525. SINDEX.C: Implements the sindex() string routine
  526.  
  527. char *sindex(s, pat)
  528. /* Searches for the string pat within the string s. */
  529. /* Returns the pointer to the portion of the string where this occurs, */
  530. /* or NULL if it doesn't occur */
  531. register char *str;
  532. register char *pat;
  533.  
  534. Include files: NSTRING.H
  535. See also: 
  536. -----------------------------------------------------------------
  537. STRING.C: Various miscellaneous string routines
  538.  
  539. str_upper(s)    /* Converts string to upper case */
  540. register char *s;
  541.  
  542. char *pstrcpy(dest, source)
  543. /* Does a strcpy, but returns the address of the NIL in dest */
  544. register char *dest;
  545. register char *source;
  546. This is useful for appending together many strings without wasting CPU
  547. time.  Upon copying source to dest, it returns the address of the NIL
  548. it just wrote in dest, allowing you to pstrcpy() another string there
  549. to append.  For example, to append strings s1, s2 and s3 into d:
  550.     char *c;
  551.     c = pstrcpy(d, s1);
  552.     c = pstrcpy(c, s2);
  553.     c = pstrcpy(c, s3);
  554.  
  555. char *strdup(string)
  556. register char *string;
  557. Allocates new memory for a string the same length of string using
  558. malloc(), and copies the old to the new.
  559.  
  560. char *pstrlen(s)
  561. char *s;
  562. Finds the NIL character in s and returns its addresss.
  563.  
  564. Include files: NSTRING.H
  565. See also: 
  566. -----------------------------------------------------------------
  567. TRICKS.C: Memory allocation tricks
  568.  
  569. char *malloc_highend(size)
  570. /* Malloc's at the high end of memory */
  571. LONG size;
  572.  
  573. /* Allocates a "permanent" memory block in high memory */ char
  574. *PMalloc(size) LONG size; The memory that this allocates will stay
  575. around after a Pterm() call because it's made to officially belong to
  576. the Desktop or TOS, some process that never exits.  This works only on
  577. TOS 1.4 or greater.  It uses entirely documented variables, but
  578. temporarily modifies one which ATARI says should never be touched.  It
  579. does work.
  580.  
  581. term_res(out)
  582. /* Terminates and stays resident, saving the text, data, bss and basepage */
  583. int out;        /* Output code */
  584.  
  585. Include files: TRICKS.H
  586. See also: 
  587. -----------------------------------------------------------------
  588. UPROOT.C
  589.  
  590.  * routine to send a one-shot media-definitely-changed
  591.  * message to GEMDOS (via Rwabs).
  592. uproot(drv)
  593. int drv;
  594.  
  595. Include files: 
  596. See also: 
  597. -----------------------------------------------------------------
  598. VOLUME.C: Get and set the volume name of a disk
  599.  
  600.  *      Returns TOS error code in case of trouble
  601. int get_vname(drvnum, label)
  602. int  drvnum;
  603. char *label;
  604. The volume label returned is "NOLABEL" if there's no label on the disk.
  605.  
  606.  * set_vname
  607.  *      Replaces old volume name(s) with new one
  608.  *      Deletes volume name if newname is empty string (old TOS only)
  609.  *      Returns TOS error code in case of trouble
  610. int set_vname(drvnum, newname)
  611. int drvnum;
  612. char *newname;
  613.  
  614. Include files: 
  615. See also: 
  616. -----------------------------------------------------------------
  617. WHERIS.C: Stuff for searching environment variables
  618.  
  619. BOOLEAN existf(n)   /* Finds out if file n exists */
  620. char *n;
  621.  
  622. search_env(envvar, fname, fullname, use_this)
  623. /* Searches all the directories in the environment variable */
  624. /* envvar and tests each one, according to use_this(), to see */
  625. /* if it is wanted.  When use_this() returns TRUE, it quits */
  626. char *envvar;       /* The environment variable to search on */
  627. char *fname;        /* The file leaf name */
  628. char *fullname;     /* The full pathname to output */
  629. BOOLEAN (*use_this)();
  630.     /* Routine to determine which file names to keep & which to throw out */
  631.     /* Returns a TRUE to stop the execution */
  632. use_this() should be declared as: BOOLEAN use_this(name) char *name;
  633.  
  634. wheris(envvar, fname, fullname)
  635. /* Finds an already made file from an environment variable */
  636. char *envvar;       /* The environment variable to search on */
  637. char *fname;        /* The file leaf name */
  638. char *fullname;     /* The full pathname to output */
  639.  
  640. This searches the environment variable, which is assumed to containe a
  641. list of folders.  It checks each to see if the file fname is in that
  642. folder. 
  643.  
  644. first_path(envvar, fname, fullname)
  645. /* Matches fname with the first directory in envvar */
  646. char *envvar;       /* The environment variable to search on */
  647. char *fname;        /* The file leaf name */
  648. char *fullname;     /* The full pathname to output */
  649.  
  650. This sees if fname is in the first folder listed in the environment
  651. variable envvar.
  652.  
  653. Include files: 
  654. See also: 
  655. -----------------------------------------------------------------
  656. WHICHTOS.C
  657.  
  658.  * whichtos(&version, &date)
  659.  *  Returns TOS version and TOS build date in its arguments
  660. void whichtos(tosver, tosdate)
  661. unsigned *tosver, *tosdate;
  662.  
  663. Include files: 
  664. See also: 
  665. -----------------------------------------------------------------
  666. WILD.C: Fancy wildcard-matching routines
  667.  
  668. BOOLEAN match_wild(wild, stringg)   /* Sees if stringg matches with wild */
  669. char *stringg;
  670. char *wild;
  671. This matches strings against wildcards, but without '.' as a special
  672. character.  Thus, anything matches to '*', and only items with a '.'
  673. in them match to '*.*'
  674.  
  675.  
  676. BOOLEAN match_fwild(wild, fname)
  677. /* Matches a file wildcard to a file -- takes care of '*.*' */
  678. char *wild;
  679. char *fname;
  680. This matches filenames just the way that GEMDOS does it.  Thus, '*.*'
  681. here means all files.
  682.  
  683. BOOLEAN match_fwilds(wild, fname)
  684. /* Matches a whole sequence of wildcards to a file */
  685. char *wild;         /* The string of wildcards */
  686. char *fname;        /* Leaf_name to match to the wildcards */
  687.  
  688. This matches a file against a sequence of wildcards as found in The
  689. Vault: If you give more than one mask, \vault\ uses them from left to
  690. right.  For example, *.pas *.c backs up all the `.PAS' and `.C' files.
  691. A mask preceded by an exclamation point (!) excludes the matching
  692. files.  For example, *.* !*.BAK backs up all files except the `.BAK'
  693. files.  Each new mask adds to or subtracts from the set of files
  694. specified by all preceding masks. For example, *.* !TEST.* *.C starts
  695. with all files, then removes those matching `TEST.*', then adds back
  696. all files matching `*.C'.  Note that `TEST.C' will be backed up by
  697. these rules. 
  698.  
  699. Include files: 
  700. See also: 
  701. -----------------------------------------------------------------
  702. WINDNEW.C
  703.  
  704. /* Binding for the wind_new() command documented in the */
  705. /* Rainbow TOS Release Notes */
  706. wind_new()
  707.  
  708. Wind_new() does something like initalize the window manager.  Warning:
  709. this does NOT check for TOS 1.4 or greater.
  710.  
  711. Include files: 
  712. See also: 
  713. -----------------------------------------------------------------
  714. -----------------------------------------------------------------
  715. COROUTINES: Coroutines gives your application limited multitasking.
  716. It doesn't allow two processes to run simultaneously, but it _does_
  717. allow them to pass off control from one to the other.
  718.  
  719. In regular C code, suppose you have something such as:
  720.     int a() {~~~~~a bunch of code~~~~~}
  721.     int b() {~~~~~a bunch of code~~~~~ a(); ~~~~~a bunch of code~~~~~}
  722.  
  723. Then function b() would become the master and function a() the slave.
  724. Function a() runs to completion and then reports some answer back to
  725. b().  But suppose you wanted a() to report back to b() in the middle
  726. of running, and then resume again at b()'s discression.  That's what
  727. coroutines are for.
  728.  
  729. The master process is allowed to start as many slave processes at it
  730. wants.  Each time it does this, the slave process runs until it
  731. decides to report back to the master by a subroutine call.  The master
  732. then continues running as if the slave had returned, _but_ it can let
  733. the slave continue at any point it wishes.  Below are the details of
  734. the routines.  Look at the file COSAMPLE.C to see how it works.
  735.  
  736. CCOMON.S: Part of the Coroutine Package
  737.  
  738. * Process control block structure
  739. * typedef enum {P_NEW, P_BLOCKED, P_READY, P_RUNNING, P_DEAD} procstate;
  740. *
  741. * typedef struct {
  742. *   proc_state state;       process state
  743. *   char *stack;            current stack pointer
  744. *   message *msg;           message value
  745. * } pcb
  746.  
  747. * Coroutine master
  748. * Uses C calling conventions
  749.  
  750. * invoke(f, x, p)
  751. * Calls f(x) in process p.  Returns when p blocks or terminates.
  752. *   func *f;    Function to call
  753. *   LONG x;     argument to give it
  754. *   pcb *p;     process control block for that function
  755. *
  756.  
  757. * BOOLEAN resume(p, m, ret_msg)
  758. *   pcb *p;
  759. *   message m;
  760. *   message *ret_msg;   Return message from slave
  761. * returns FALSE if p terminates, TRUE if it's still going
  762. *
  763. * Called by master.
  764. * Resumes process p, which should be in state P_READY.
  765. * Passes p.msg to the resumed process as a returned value.
  766.  
  767. * message to_master(to_msg)
  768. *   message to_msg
  769. *
  770. * Called by slave function.
  771. * Blocks current process and passes control back to master.
  772. * When process is resumed, the message in the pcb is passed as
  773. * the value of the function.
  774.  
  775. CO.C: The C part of coroutines
  776.  
  777. BOOLEAN init_co(f, arg, stacksize, p)
  778. /* Returns FALSE on error */
  779. func *f;        /* Cofunction to init */
  780. LONG arg;       /* Argument to that function */
  781. long stacksize; /* Size of stack to make */
  782. pcb *p;         /* Process stack ID to put stack in */
  783. This makes a process out of a function, giving it a stack and a pcb.
  784. You must always call init_co() on a slave before you call invoke()
  785.  
  786. kill_co(p)  /* This kills a coroutine by freeing its stack */
  787. pcb *p;
  788. You don't have to have let the coroutine terminate before you kill it.
  789.  
  790. Include files: 
  791. See also: COSAMPLE.C
  792. -----------------------------------------------------------------
  793. -----------------------------------------------------------------
  794. Virtual Files:
  795.  
  796. In the normal C library, you can open a file off of the disk and read
  797. it using primitives such as getc(), etc.  You can even redirect input
  798. and output from various sources, such as the keyboard, the modem port,
  799. etc.  Virtual files extend this idea by giving you the possibility to
  800. redirect output from any means which can implement the VFILE
  801. primitives: a normal file, a block of memory, even a coroutine!
  802.  
  803. The vfile primitives are vfread() and vfwrite().  You aren't allowed
  804. to seek in virtual files.  You can then link on extra modules to give
  805. different kinds of virtual files, by writing a read, write, open and
  806. close for every specific kind of virtual file.  Lookat FFILE.C for a
  807. simple, specific example.
  808.  
  809. unsigned vfread(buf, size, num, file)            /* Analog of fread() */
  810. /* Returns number of chars read */
  811. char *buf;      /* Buf to read to */
  812. unsigned size;  /* Size of data objects */
  813. unsigned num;   /* Number of objects */
  814. VFILE *file;    /* File to read from */
  815.  
  816. long vfwrite(buf, size, num, file)            /* Analog of fwrite() */
  817. /* As a hack, this does not return any error, ever.  It always returns
  818.    num, pretending there's no error. */
  819. char *buf;      /* Buf to read to */
  820. unsigned size;  /* Size of data objects */
  821. unsigned num;   /* Number of objects */
  822. VFILE *file;    /* File to read from */
  823.  
  824. BOOLEAN vputs(out, s)   /* Writes the string s to out, doesn't append '\n' */
  825. VFILE *out;     /* File to write to */
  826. register char *s;        /* String to write */
  827.  
  828. Following are various modules for virtual files:
  829.  
  830. Include files: VFILE.H
  831. See also: PICTURE.C for some good examples of how to use virtual files.
  832. -----------------------------------------------------------------
  833. FFILE.C
  834. /* VFILE driver for normal C streams */
  835.  
  836. VFILE *open_ffile(name, mode)   /* Works just like fopen() */
  837. char *name;
  838. char *mode;
  839.  
  840. Include files: VFILE.H
  841. See also: 
  842. -----------------------------------------------------------------
  843. MEMFILE.C: MFILE lets you treat a block of memory as a sequential
  844. file.  For example, if you have a picture in memory and you have a
  845. program which expects to read a picture from a VFILE, you'd make the
  846. picture into a MFILE.
  847.  
  848. /* Memory file driver for VFILE */
  849. typedef struct {    /* A file in memory */
  850.     char *base;     /* Base of the file */
  851.     char *end;      /* Last char in file +1 */
  852.     char *next;     /* Next character to be read or written */
  853.     BOOLEAN eof;    /* Has end of file been reached? */
  854. } MFILE;
  855.  
  856. VFILE *open_mfile(base, len)
  857. /* This opens an MFILE and returns a VFILE * */
  858. char *base;     /* Start of MFILE */
  859. long len;           /* Length of MFILE */
  860.  
  861. Include files: VFILE.H
  862. See also: 
  863. -----------------------------------------------------------------
  864. COFILE.C: Cofiles use coroutines and virtual files.  It allows the
  865. master to read and write to the slave process as if it's a file, and
  866. the slave receives read and write commands from the master as if it's
  867. reading and writing from a file.  Generally, you set it up so the
  868. slave is either always reading or always writing.
  869.  
  870. typedef struct  {   /* A slave's end of the the cofile */
  871.     long    size;
  872.     BOOLEAN eof;
  873. } SLAVE_FILE;
  874. typedef struct {
  875.     pcb     f;      /* The function which the cofile is made of */
  876.     long    size;   /* Current size of file (amount read or written) */
  877.     BOOLEAN eof;    /* TRUE if end of file has been reached */
  878.     SLAVE_FILE *slave;
  879. } COFILE;
  880.  
  881. VFILE *open_cofile(f, x, stacksize, slave_vfile)
  882. func *f;        /* Function to make a cofile of */
  883. LONG x;         /* Argument to f */
  884. long stacksize; /* Size to make cofile's stack */
  885. VFILE **slave_vfile;        /* Slave's cofile handle */
  886.  
  887. Include files: VFILE.H 
  888. See also: 
  889. -----------------------------------------------------------------
  890. HEADER FILES:
  891.  
  892. Header files in LynxLib generally have the form, for a header file
  893. called FOO.H:
  894.  
  895. #ifndef FOO_H
  896. #define FOO_H
  897.  
  898. ~~~~ definitions for FOO.H ~~~~~~
  899.  
  900. #endif
  901.  
  902. This way, you can include FOO.H as many times as you like without ill
  903. effects.  Following are header files not associated with a specific
  904. module above:
  905.  
  906. E_OSBIND.H:
  907. You shouldn't need to ever use this.  It #includes TOS.H, TOSMEM.H,
  908. SYSVAR.H and VT52.H, and is only included for compatibility with an
  909. old version of LynxLib.
  910.  
  911. LINEA.H:
  912. Common include file for C interface to low level Line A calls, by:
  913.     J.R. Bammi
  914.     decvax!cwruecmp!bammi
  915.     bammi%case@csnet-relay.ARPA
  916.     bammi@case.CSNET
  917.  
  918. NOBDEFS.H:
  919. This is the standard OBDEFS.H header file, but with some
  920. changes.  It is to be used in place of OBDEFS.H.  The structure OBJECT
  921. is the same, except that the element ob_spec, instead of just being a
  922. LONG, is now a union of bitfields and such, allowing you to access
  923. color bits, etc. easily.  Unfortunately, you can't initalize
  924. bitfields, so I've included the structure MW_OBECT, which is the same
  925. as Mark William's definition of OBJECT. 
  926.  
  927. STDDEF.H:
  928.  
  929. These are standard definitions which are used just about everywhere.
  930. One note, NULL means a NULL pointer.  NIL is the character terminating
  931. strings. 
  932.  
  933. The structures xywh and such are mostly useful when defining boxes (as
  934. in AES and VDI).
  935.  
  936. The new() macro makes life really easy for allocating memory.  Given a
  937. pointer p to some structure, such as:
  938.     typedef struct {
  939.         int a,b;
  940.     } X_STRUCT;
  941.     X_STRUCT *p;
  942.  
  943. You can now replace "p = malloc(sizeof(X_STRUCT))" with "new(p)".  It
  944. reduces typing and is also semantically more correct.  If you happened
  945. to change the type of p from *X_STRUCT to *Y_STRUCT, the malloc() call
  946. would become wrong, but the new() call would continue to work. 
  947.  
  948. The definitions leaf_name, fle_name, file_root and file_extender are
  949. strings to hold various parts of file names.
  950.  
  951. STRING.H: The standard STRING.H found on most C-compilers, but not in MWC.
  952.  
  953. STRINGS.H: There's some confusion about whether STRING.H is not
  954. STRINGS.H.  Programs which include STRING.H or STRINGS.H will work
  955. with this.
  956.  
  957. SYSVAR.H:
  958. This defines all the documented (and one undocumented, in TOS 1.0)
  959. variables, in a way which is useful.  They're all casted in such a way
  960. that you need only use them (but make sure you go into supervisor mode
  961. first).  For example, FVERIFY is a flag found at 0x444.  To change its
  962. value, simply use "FVERIFY = 17;", or whatever.  VBLQUEUE is an array
  963. of pointers to functions.  To look at the sixth entry, use
  964. VBLQUEUE[6].  The lower-case variables are the same, except without
  965. any fancy casting.
  966.  
  967. TOS.H:
  968. A greatly expanded version of the standard OSBIND.H file.  In
  969. addition to the standard macro definitions, it includes many many many
  970. structures used by GEMDOS and BIOS, and error return codes.  The
  971. definitions are arranged by the function they're used with.
  972.  
  973. TOSMEM.H:
  974. More structures used by TOS, but these aren't usually as useful as
  975. those in TOS.H
  976.  
  977. VT52.H:
  978. The VT-52 escape sequences for screen display.
  979.  
  980. ROUND.O:
  981. Various things for rounding and dividing.
  982.