home *** CD-ROM | disk | FTP | other *** search
/ Gold Fish 1 / GoldFishApril1994_CD1.img / d1xx / d126 / suplib / suplib.doc < prev    next >
Text File  |  1988-01-02  |  11KB  |  310 lines
  1.  
  2. SUPLIB.DOC    General C Support Library
  3.  
  4.  
  5.     Compile all modules using a precompiled symbol table of all the
  6.     AMIGA include's (*/*.H) ... do *NOT* include standard aztec
  7.     includes (stdio.h, etc...).
  8.  
  9.     You must use the +L option (32 bit ints) for ALL COMPILATIONS, including
  10.     the generation of the symbol table.
  11.  
  12.  
  13. Summary of Modules:
  14.  
  15.     XFIO:    Asyncronous file IO.  Allows sequential asyncronous access
  16.         to files for both reading (reads ahead asyncronously) and
  17.         writing (writes asyncronously).  Usually employed by CPU
  18.         bound programs not wishing to be slowed down even more by
  19.         the disk.  Extremely useful for implementation of capture
  20.         and serial protocols.
  21.  
  22.  
  23.     DIO:    Device IO package.  This is a Generic interface for handling
  24.         the Amiga's EXEC devices.  It makes your code smaller and
  25.         much easier to read.  You no longer need to be a guru to
  26.         use devices.
  27.  
  28.     BSTRING:    memory move/set/compare routines.  Operations are done in
  29.         longwords when possible.
  30.  
  31.     MISC:    misc. routines (break checking, openning/closing libraries)
  32.  
  33.  
  34.  
  35.  
  36.     xfi =   xfopen(file, mode, bytes)
  37.     err =   xfclose(xfi)
  38.      n    =   xfread(xfi, buf, n)
  39.      n    =   xfgets(xfi, buf, max)
  40.     err =   xfwrite(xfi, buf, n)
  41.  
  42.         mode is "r", "w", or "w+".  No seeking is allowed as you can
  43.         see.  If you openned for reading, you may NOT use xfwrite(),
  44.         and if you openned for writing, you may NOT use xfread().
  45.  
  46.         The specified buffer size (bytes) is used to create two
  47.         buffers of (bytes/2) bytes, double buffering either
  48.         asyncronous read ahead, or asyncronous writes.
  49.  
  50.         'err' returns 1 if a write error occured.  err is returned
  51.         by xfclose() (xfclose() waits for any asyncronous writes
  52.         to complete and thus can return whether they failed or not).
  53.         Once set, err stays set forever.
  54.  
  55.         XFREAD: 0 is returned on EOF or error
  56.         XFGETS: the length of the string is returned.  0 is a valid
  57.             length (a blank line).  -1 is returned on EOF or
  58.             error.    The newline is removed and a string
  59.             terminator (0) added.
  60.  
  61. ********* BSTRING *******
  62.  
  63.         bmov(src,dest,bytes)
  64.         bcmp(src,dest,bytes)
  65.         bset(src, bytes, c)
  66.         bzero(src, bytes)
  67.  
  68.         These functions do various memory operations.  bcmp() is
  69.         unsigned, of course.  bmov() uses acending or decending
  70.         mode as appropriate.  All routines will do operations in
  71.         longwords if the src, dest, and bytes are on longword
  72.         boundries.
  73.  
  74. ********* MISC **********
  75.  
  76.         checkbreak()
  77.         resetbreak()
  78.         disablebreak()
  79.         enablebreak()
  80.  
  81.         [disable/enable]break() is used to disable automatic
  82.         break check-and-exit by STDIO.    [check/reset]break() is
  83.         used by your program after you have disabled check-and-exit
  84.         with disablebreak() to do your own break checking.
  85.  
  86.         checkbreak() returns TRUE when break has been pressed.  The
  87.         'break pressed' flag is cleared by resetbreak().
  88.  
  89.  
  90.         openlibs(flags)
  91.         closelibs(flags)
  92.  
  93.         see XMISC.H for flag definitions.  openlibs() opens all
  94.         specified libraries, returning 0 if one or more could not
  95.         be openned.  closelibs() closes all specified libraries.
  96.         closelibs(-1) closes ALL open libraries.  (NOTE: you cannot
  97.         open/close DOS or EXEC.  This is because the C startup
  98.         and exit will do this for you).
  99.  
  100.     n = atoi(str)
  101.  
  102.         returns the decimal value of the specified string.  The
  103.         routine uses shifts instead of multiply internally.
  104.  
  105.      bool = wildcmp(wildstr, namestr)
  106.  
  107.         compare the wildcard string (containing '*'s and '?'s) with
  108.         the file name (namestr) and return TRUE (1) if they compare,
  109.         and FALSE (0) otherwise.
  110.  
  111.         mountrequest(bool)
  112.  
  113.         enable or disable the DOS requester which comes up when
  114.         you attempt to open a path not currently mounted.  Normal
  115.         mode is TRUE (1), meaning that you get the requester.
  116.  
  117.         fhprintf(fh, ctrlstr, args...)
  118.  
  119.         uses the EXEC formatted printing call to format text and
  120.         then writes it to a DOS file handle.
  121.  
  122.         llink(list, en)
  123.         lunlink(en)
  124.  
  125.         see XMISC.H .  Simple doubly-linked list routines.  XLIST
  126.         is both the list base and an element.  The list base should
  127.         be initialized to zero before use.
  128.  
  129. ********* DIO ***********
  130.  
  131.     EXEC device driver IO support routines... makes everything easy.
  132.  
  133.     dfd = dio_open(name, unit, flags, req/NULL)
  134.  
  135.       open an IO device.  Note: in some cases you might have to provide a
  136.       request structure with some fields initialized (example, the console
  137.       device requires certain fields to be initialized).  For instance, if
  138.       openning the SERIAL.DEVICE, you would want to give an IOExtSer
  139.       structure which is completely blank execept for the io_SerFlags
  140.       field.
  141.  
  142.       The request structure's message and reply ports need not be
  143.       initialized.  The request structure is no longer needed after
  144.       the dio_open().
  145.  
  146.       returns NULL = error, else DIO descriptor (a pointer) returned.
  147.  
  148.  
  149.   dio_close(dfd)
  150.  
  151.       close an IO device.  Any pending asyncronous requests are
  152.       AbortIO()'d and then Wait'ed on for completion.
  153.  
  154.  
  155.   dio_closegrp(dfd)
  156.  
  157.       close EVERY DIO DESCRIPTOR ASSOCIATED WITH THE dio_open() call
  158.       that was the parent for this descriptor.    That is, you can get
  159.       a descriptor using dio_open(), dio_dup() it a couple of times,
  160.       then use dio_closegrp() on any ONE of the resulting descriptors
  161.       to close ALL of them.
  162.  
  163.  
  164.   dio_cact(dfd,bool)
  165.  
  166.       If an error occurs (io_Error field), the io_Actual field is usually
  167.       not modified by the device driver, and thus contains garbage.  To
  168.       provide a cleaner interface, you can have the DIO_CTL() and
  169.       DIO_CTL_TO() calls automatically pre-clear this field so if an
  170.       io_Error does occur, the field is a definate 0 instead of garbage.
  171.  
  172.       In most cases you will want to do this.  An exception is the
  173.       TIMER.DEVICE, which uses the io_Actual field for part of the timeout
  174.       structure.
  175.  
  176.       This flags the particular dio descriptor to do the pre-clear, and any
  177.       new descriptors obtained by DIO_DUP()ing this one will also have the
  178.       pre-clear flag set.
  179.  
  180.  
  181.   dio_dup(dfd)
  182.  
  183.       Returns a new channel descriptor referencing the same device. The new
  184.       descriptor has it's own signal and IO request structure. For
  185.       instance, if you openned the serial device, you might want to dup the
  186.       descriptor so you can use one channel to pend an asyncronous read,
  187.       and the other channel to write out to the device and do other things
  188.       without disturbing the asyncronous read.
  189.  
  190.  
  191.   sig = dio_signal(dfd)
  192.  
  193.       get the signal number (0..31) used for a DIO descriptor. This allows
  194.       you to Wait() for asyncronous requests.  Note that if your Wait()
  195.       returns, you should double check using dio_isdone()
  196.  
  197.  
  198.   req = dio_ctl_to(dfd, command, buf, len, to)
  199.  
  200.       Same as DIO_CTL() below, but (A) is always syncronous, and (B) will
  201.       attempt to AbortIO()+WaitIO() the request if the timeout occurs
  202.       before the IO completes.
  203.  
  204.       the 'to' argument is in microseconds.
  205.  
  206.       If timeout occurs before request completes, and DIO aborts the
  207.       request, some devices, such as the SERIAL.DEVICE do not have the
  208.       io_Actual field set properly.  Always check the io_Error field for
  209.       an abort before using io_Actual.
  210.  
  211.  
  212.   req = dio_ctl(dfd, command, buf, len)
  213.  
  214.       DIO_CTL() is the basis for the entire library.  It works as follows:
  215.  
  216.       (1) If the channel isn't clear (there is an asyncronous IO request
  217.       still pending), DIO_CTL() waits for it to complete
  218.  
  219.       (2) If the command is 0, simply return a pointer to the io
  220.       request structure.
  221.  
  222.       (3) If the DIO_CACT() flag is TRUE, the io_Actual field of the
  223.       request is cleared.
  224.  
  225.       (4) Set the io_Data field to 'buf', and io_Length field to 'len'
  226.       If the command is positive, use DoIO().  If the command
  227.       negative, take it's absolute value and then do a SendIO().
  228.       (The command is placed in the io_Command field, of course).
  229.  
  230.       (5) return the IO request structure
  231.  
  232.  
  233.   bool= dio_isdone(dfd)
  234.  
  235.       return 1 if current channel is clear (done processing), else 0. e.g.
  236.       if you did, say, an asyncronous read, and dio_isdone() returns true,
  237.       you can now use the data buffer returned and look at the io_Actual
  238.       field.
  239.  
  240.       You need not do a dio_wait() after dio_isdone() returns 1.
  241.  
  242.  
  243.   req = dio_wait(dfd)
  244.  
  245.       Wait on the current channel for the request to complete and then
  246.       return the request structure. (nop if channel is clear)
  247.  
  248.  
  249.   req = dio_abort(dfd)
  250.  
  251.       Abort the request on the current channel (nop if channel is
  252.       clear).  Sends an AbortIO() if the channel is active and then
  253.       WaitIO()'s the request.
  254.  
  255.     ------ MACROS ------
  256.  
  257.     dio_simple() and related macros return the !io_Error field. That
  258.     is, 0=ERROR, 1=OK
  259.  
  260.     dio_actual() returns the io_Actual field instead of !io_Error.
  261.  
  262.     NOTE: the io_Actual field may not be set by the device if an
  263.     error condition exists.  To make the io_ctl() and io_ctl_to()
  264.     call automatically clear the io_Actual field before doing the
  265.     io operation, use the DIO_CACT() call.  The reason this isn't
  266.     done automatically by default is that some devices require
  267.     parameters to be passed in the io_Actual field (like the
  268.     timer.device).
  269.  
  270.     Remember, Asyncronous IO is done by sending -com instead of com.
  271.     (that is, negative command).
  272.  
  273.       CALL              Syncronous IO   Asyncronous IO
  274.  
  275.   dio_simple(dfd,com)             0=ERROR, 1=OK   undefined
  276.   dio_actual(dfd,com)             io_Actual       undefined
  277.   dio_reset(dfd)                  0=ERROR, 1=OK   n/a
  278.   dio_update(dfd)                 0=ERROR, 1=OK   n/a
  279.   dio_clear(dfd)                  0=ERROR, 1=OK   n/a
  280.   dio_stop(dfd)                   0=ERROR, 1=OK   n/a
  281.   dio_start(dfd)                  0=ERROR, 1=OK   n/a
  282.   dio_flush(dfd)                  0=ERROR, 1=OK   n/a
  283.   dio_getreq(dfd)                 returns a ptr to the IO
  284.                   request structure
  285.  
  286.       NOTE: If you use the following, you probably want to have the device
  287.       library automatically clear the io_Actual field before sending the
  288.       request so you get 0 if an error occurs.    That is: dio_cact(dfd,1):
  289.  
  290.   dio_read(dfd,buf,len)           returns actual bytes read
  291.   dio_write(dfd,buf,len)          returns actual bytes written
  292.  
  293.     The timeout argument for dio_readto() and dio_writeto()
  294.     is in MICROSECONDS, up to 2^31uS.
  295.  
  296.   dio_readto(dfd,buf,len,to)      returns actual bytes read
  297.   dio_writeto(dfd,buf,len,to)     returns actual bytes written
  298.  
  299.     The asyncronous dio_reada() and dio_writea() do not
  300.     return anything.
  301.  
  302.   dio_reada(dfd,buf,len)          begin asyncronous read
  303.   dio_writea(dfd,buf,len)         begin asyncronous write
  304.  
  305.  
  306.  
  307.  
  308.  
  309.  
  310.