home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d168 / doc / suplib / suplib.doc < prev   
Text File  |  1988-11-22  |  10KB  |  314 lines
  1.  
  2. SUPLIB.DOC    General C Support Library
  3.  
  4.                 COMPILATION
  5.  
  6.     Compile all modules using a precompiled symbol table of all the
  7.     AMIGA include's (*/*.H) ... do *NOT* include standard aztec
  8.     includes (stdio.h, etc...).  The Makefile for the precompiled symbol
  9.     table is in the LOCAL directory.
  10.  
  11.     You must use the +L option (32 bit ints) for ALL COMPILATIONS, including
  12.     the generation of the symbol table when compiling SUPLIB (SUP32.LIB).
  13.     Also, use +B (no .begin reference), +CD (large code and data) model
  14.     when compiling this source.
  15.  
  16.  
  17.                     MODULES
  18.  
  19.     QINT:    These are exception based prioritized software interrupt
  20.         routines.  see QINT.DOC
  21.  
  22.     ASYNCOP:    Asynchronous function execution.  Make asynchronous
  23.         function calls (not incredibly fast).
  24.  
  25.     XFIO:    Asyncronous file IO.  Allows sequential asyncronous access
  26.         to files for both reading (reads ahead asyncronously) and
  27.         writing (writes asyncronously).  Usually employed by CPU
  28.         bound programs not wishing to be slowed down even more by
  29.         the disk.  Extremely useful for implementation of capture
  30.         and serial protocols.
  31.  
  32.     DIO:    Device IO package.  This is a Generic interface for handling
  33.         the Amiga's EXEC devices.  It makes your code smaller and
  34.         much easier to read.  You no longer need to be a guru to
  35.         use devices.
  36.  
  37.     BSTRING:    memory move/set/compare routines.  Operations are done in
  38.         longwords when possible.
  39.  
  40.     SYS:    System enhancement calls
  41.  
  42.     MISC:    misc. routines (break checking, openning/closing libraries),
  43.         date and time routines, setfiledate, etc...
  44.  
  45.  
  46.     ---------------------------------------------------------------------
  47.  
  48.                    QINTS
  49.  
  50.     SEE QINT.DOC
  51.  
  52.  
  53.                   ASYNCH OP
  54.  
  55. handle= NewAsyncOp()
  56.  
  57.     Create a new task for handling asynchronous function calls.
  58.  
  59. (void)  StartAsyncOp(handle, func, arg1, arg2, arg3)
  60.  
  61.     Queue up a function for the handle.  Multiple functions may
  62.     be queueud.  NOTE:  The registers A4 and A5 will be initialized
  63.     to what they were when NewAsyncOp() was called.
  64.  
  65.     The function must preserve D4-D7/A2-A3.  D0-D3/A0-A1/A4-A6 may
  66.     be destroyed by the function.
  67.  
  68.  
  69. bool  = CheckAsyncOp(handle, n)
  70.  
  71.     Return TRUE if a minimum of N async operations started with
  72.     StartAsyncOp() have completed, FALSE otherwise.  The number
  73.     of async operations in progress is the number started minus
  74.     the number already waited for.
  75.  
  76. (void)= WaitAsyncOp(handle, n)
  77.  
  78.     Wait for N of the operations in progress to complete.  -1 can
  79.     be specified to wait for ALL the operations in progress to
  80.     complete.
  81.  
  82.     For example, if you queue up 3 commands, CheckAsyncOp(handle, 3)
  83.     will check if all 3 have completed, and WaitAsyncOp(handle, 3)
  84.     waits and removes their reply messages as well as adjusts the
  85.     number of 'operations in progress' to 0.
  86.  
  87.     I.E, if you were to WaitAsyncOp(handle, 2) instead of 3, after
  88.     it returns there will be 1 operation in progress left.    If you
  89.     were to do another StartAsyncOp(), there would now by 2 in
  90.     progress.
  91.  
  92. (void)  CloseAsyncOp(handle)
  93.  
  94.     Wait for all operations in progress to end (WaitAsyncOp(handle,-1)),
  95.     then remove the task.
  96.  
  97.                  XFIO
  98.  
  99.  
  100.     xfi =   xfopen(file, mode, bytes)
  101.     err =   xfclose(xfi)
  102.      n    =   xfread(xfi, buf, n)
  103.      n    =   xfgets(xfi, buf, max)
  104.     err =   xfwrite(xfi, buf, n)
  105.  
  106.         mode is "r", "w", or "w+".  No seeking is allowed as you can
  107.         see.  If you openned for reading, you may NOT use xfwrite(),
  108.         and if you openned for writing, you may NOT use xfread().
  109.  
  110.         r   read
  111.         w   write-newfile
  112.         w+  write-append
  113.  
  114.         The specified buffer size (bytes) is used to create two
  115.         buffers of (bytes/2) bytes, double buffering either
  116.         asyncronous read ahead, or asyncronous writes.
  117.  
  118.         'err' returns 1 if a write error occured.  err is returned
  119.         by xfclose() (xfclose() waits for any asyncronous writes
  120.         to complete and thus can return whether they failed or not).
  121.         Once set, err stays set forever.
  122.  
  123.         XFREAD: 0 is returned on EOF or error
  124.         XFGETS: the length of the string is returned.  0 is a valid
  125.             length (a blank line).  -1 is returned on EOF or
  126.             error.    The newline is removed and a string
  127.             terminator (0) added.
  128.  
  129.  
  130.                 DIO
  131.  
  132.      SEE DIO.DOC
  133.  
  134.  
  135.                    BSTRING
  136.  
  137. (void)  bmov(src,dest,bytes)
  138. bool  = bcmp(src,dest,bytes)
  139. (void)  bset(src, bytes, c)
  140. (void)  bzero(src, bytes)
  141.  
  142.     These functions do various memory operations.  bcmp() is does an
  143.     unsigned comparison, of course.  bcmp() only checks for
  144.     equivalence, returning TRUE (1) if the buffers are the same,
  145.     FALSE (0) otherwise.  bcmp() uses longword compares when possible.
  146.  
  147.     bmov() does an ascending or decending copy as appropriate.
  148.     bmov(), bzero(), and bset() use longword and MULTIPLE REGISTER
  149.     operations when possible.
  150.  
  151.     These functions are the same as the BSet(), BZero(), BMov(), and
  152.     BCmp() in my run-time library DRES.LIBRARY.
  153.  
  154. bool =    checkbreak()
  155.  
  156.     Check whether the process has received a ^C or ^D signal.  ^D
  157.     is also checked here allowing a more reliable break-mechanism,
  158.     as Aztec and Lattice stdio routines will clear ^C even when
  159.     break is disabled.
  160.  
  161. (void)  resetbreak()
  162. (void)  disablebreak()
  163. (void)  enablebreak()
  164.  
  165.     resetbreak() clears both the ^C and ^D signals.  disablebreak()
  166.     and enablebreak() modify the global variable Enable_Abort and
  167.     thus stdio's automatic break detection/abort.
  168.  
  169.  
  170. bool  = openlibs(flags)
  171. bool  = closelibs(flags)
  172.  
  173.     See the flag definitions in XMISC.H.  openlibs() opens all
  174.     specified libraries, returning 0 if one or more could not
  175.     be openned.  closelibs() closes all specified libraries.
  176.     openlibs() does not open a library that is already open (if you
  177.     make the call more than once), and simply uses the already
  178.     open descriptor.
  179.  
  180.     closelibs(-1) closes ALL libraries openned with openlibs(), but
  181.     NOT libraries openned otherwise.
  182.  
  183.     Note that you cannot open or close DOS or EXEC.  This is because
  184.     the C startup will do this for you, and also to prevent linker
  185.     warning messages.
  186.  
  187. Window= GetConWindow()
  188.  
  189.     This functions retrieves the struct Window * from the console
  190.     device associated with this process.  NULL is returned if the
  191.     window could not be found (still, operation may not be dependable
  192.     if the process's console is not a console device).
  193.  
  194. buf   = datetos(date, buf, ctl)
  195.     DATESTAMP *date;
  196.     char *buf;
  197.     char *ctl;
  198.  
  199.     This function converts a DOS DateStamp structure into a string
  200.     and places it in the specified buffer.    ctl specifies the format
  201.     of the date by pieces (ctl can be NULL, indicating "D M Y h:m:s").
  202.  
  203.     If not NULL, ctl is a string containing combinations of the
  204.     following characters.  Spacing must also be specified.    Any
  205.     unrecognized characters are passed to the output buffer verbatim.
  206.  
  207.         D    The day     23
  208.         M    The month    Jul
  209.         Y    The year    1988
  210.         h    The hour    03
  211.         m    The minute    23
  212.         s    The seconds    04
  213.  
  214.     This function is equivalent to DateToS() in my run time library
  215.     DRES.LIBRARY
  216.  
  217. (void)  llink(list, en)         (OBSOLETE)
  218. (void)  lunlink(en)             (OBSOLETE)
  219.  
  220.     see XMISC.H .  Simple doubly-linked list routines.  XLIST is both
  221.     the list base and an element.  The list base should be initialized
  222.     to zero before use.
  223.  
  224. (void)  mountrequest(bool)
  225.  
  226.     enable or disable the DOS requester which comes up when you attempt
  227.     to open a path not currently mounted.  Normal mode is TRUE (1),
  228.     meaning that you get the requester.  This routine remembers the
  229.     previous contents of pr_WindowPtr.  The call mountrequest(0) may
  230.     be made multiple times and then mountrequest(1) will restore the
  231.     original contents of pr_WindowPtr.
  232.  
  233. RemSemaphore()
  234. FindSemaphore()     (SEE EXEC DOCUMENTATION FOR CALLING PARAMETERS)
  235. AddSemaphore()
  236.  
  237.     These functions fix the broken bindings in older Lattice and
  238.     Aztec libraries.
  239.  
  240. bool  = setfiledate(file, date)
  241.     char *file;
  242.     DATESTAMP *date;
  243.  
  244.     This function implements the new ACTION_SET_DATE packet and
  245.     sets the timestamp of a file.  You cannot set the timestamp
  246.     for the root of a filesystem with this call.
  247.  
  248.     This function is equivalent to the SetFileDate() function in
  249.     DRES.LIBRARY.
  250.  
  251. bool =    wildcmp(wildstr, namestr)
  252.  
  253.     compare the wildcard string (containing '*'s and '?'s) with
  254.     the file name (namestr) and return TRUE (1) if they compare,
  255.     and FALSE (0) otherwise.
  256.  
  257.     This function is equivalent to the WildCmp() function in
  258.     DRES.LIBRARY.
  259.  
  260. (void)  fhprintf(fh, ctrlstr, args...)
  261.  
  262.     uses the EXEC formatted printing call to format text and then
  263.     writes it to an AMIGADOS file handle.
  264.  
  265.  
  266. rval  = AutoAllocMiscResource(resno, value)
  267.  
  268.     resno: MR_SERIALPORT, SERIALBITS, PARALLELPORT, or PARALLELBITS
  269.     value:    -1 to allocate, 0 to check.
  270.  
  271.     This functions allocates or checks the specified resource.  0
  272.     (ZERO) is returned on SUCCESS (allocated or could allocate),
  273.  
  274.     NON-ZERO is returned if the resource is already allocated by
  275.     somebody else.
  276.  
  277. (void)= AutoFreeMiscResource(resno)
  278.  
  279.     Free's a resource you allocated.  YOU MUST OWN THE RESOURCE!
  280.  
  281.     Neither of these functions require you to open the misc.resource
  282.     resource.
  283.  
  284. font  = GetFont(name, ysize)
  285.  
  286.     This function searches both memory and the disk for the requested
  287.     font, and automatically opens/closes the diskfont library if it is
  288.     not already open.  It opens the font, incrementing the reference
  289.     count.
  290.  
  291. (void)  InitDeemuNW(ary, nw)
  292.     short *ary;
  293.     NW *nw;
  294.  
  295.     ary points to the 'NW','  ' Deemu[] array entry.  The NewWindow
  296.     structure is initialized according to the Deemu entry.    Currently,
  297.     TopEdge, LeftEdge, Width, Height, DetailPen and BlockPen will
  298.     be initialized... less if the Deemu entry contains less information.
  299.  
  300. char   *GetDEnv(name)
  301.     char *name;
  302.  
  303.     Return a string to the enviroment variable name, returning NULL
  304.     if it does not exist.
  305.  
  306. bool    SetDEnv(name, str)
  307.     char *name, *str;
  308.  
  309.     Set the enviroment variable name to the string str.  Return C-TRUE
  310.     (1) on success, or C-FALSE (0) on failure.
  311.  
  312.  
  313.  
  314.