[net.micro.amiga] MY.LIB documentation

dillon@CORY.BERKELEY.EDU (Matt Dillon) (09/17/86)

	This time it's complete.

-----------------------

   V1.10 MY.LIB 32-bit-int Library CALL documentation

   The library can be broken up into four parts:

   (1) XSTDIO (stdio-like routines)
   (2) MISC   (misc. support functions)
   (3) MEMORY (memory allocation and support)
   (4) STRING (string handling)


XSTDIO

   The XSTDIO routines provide the programmer with buffered file I/O much
   like STDIO routines.  XSTDIO routines offer better control over your
   enviroment, but lack in error reporting for some functions.  The
   XSTDIO routines also have the ability to double-buffer writes.

   XSTDIO routines use a File Pointer (fi), but are NOT compatible
   with STDIO routines.

   fi = xopen(name, access, bufsize)

      FILE *fi;         returned file pointer
      char *name;       file name to open
      char *access;     access modes "r", "r+", "w", "w+"
      int  bufsize;     requested buffer size, in bytes

      "r"   -read           (fail if non-existant)
      "r+"  -read and write (fail if non-existant)
      "w"   -write          (create if non-existant, truncate if exists)
      "w+"  -append         (create if non-existant, seek to end if exists)

      The minimum buffer size is 1 (calling w/ 0 is actually 1).  It is
      suggested that you use buffer sizes of at least 512 bytes.  For
      example, if you xopen() with a bufsize of 1 and write out a 20K
      block, it will be written 1 byte at a time.

      NULL is returned on error.


   result = xasync(fi, operation)

      int result;       -result of operation (depends)
      FILE *fi;         -file pointer
      int operation;    -operation

      operation = -1    -returns boolean whether async. is on or off.
                  0     -turns async OFF
                  1     -turns async-writes ON
                  2     -reserved
                  3     -(internal) waits for async. operation to complete
                  4     -(internal) don't call with this operation.

      usually one calls xasync() with operation 0 or 1 to turn off or
      on asyncronous write mode.  When ON, another buffer of the same
      size is allocated to provide the double buffering asyncronous-writes
      need.  When on, any write operation which causes the buffer to
      flush to the disk will be done asyncronously (e.g. will return before
      disk operation is complete).  This is only useful if you are not
      writing to the disk at full speed.  Since the writes are only double-
      buffered, writing at full speed WILL cause momentary block conditions
      just like normal writing.  A good use for asyncronous writes is the
      capture function of a modem program.

      Future revisions of the library will also have an asyncronous READ
      capability.



fi = xattach(fh, bufsize)

      FILE *fi;         -return file pointer
      FileHandle fh;    -source AmigaDOS file handle
      int bufsize;      -buffering size (like xopen()).

      This routine will attempt to attach a file pointer to a file handle.
      If it succedes, any further I/O should be through XSTDIO functions
      and the file pointer rather than AmigaDOS functions through the
      File Handle.

      fi returns NULL if the buffer could not be allocated.


fh = xdetach(fi)

      FileHandle fh;    -file handle
      FILE *fi;         -file pointer

      This call deallocates the XSTDIO file pointer and returns a properly
      Seek'd file handle.  It ALWAYS works.


bool  = xsetbuf(fi, newbufsize)

      int bool;            -did the operatio work?
      FILE *fi;            -file pointer
      int newbufsize;      -new buffer size.

      This operation resizes a file pointer's buffer(s).  If it fails, the
      original buffer(s) are still in place.  Remember that if xasync() is
      on for that file pointer, the actual allocated memory is twice the
      requested buffer size.


chars =  xgets(fi, buf, n)

      int chars;     -# bytes in buffer INCLUDING the termination \0.
      FILE *fi;      -file handle to get data from.
      char *buf;     -buffer to place data in
      int n;         -maximum buffer size allowed.

      This routine will retrieve a string from the file pointer until it
      reaches the end of file or a newline '\n'.  The newline is REPLACED
      by a \0 before the function returns.

      The End Of File occurs when 'chars' is 0.


bool  = xputs(fi, buf);

      int bool;      -did the operation work?
      FILE *fi;      -file pointer
      char *buf;     -\0 terminated string

      xputs() writes the specified string to the specified file pointer.
      The \0 in the string is replaced with a newline '\n' in the output.


c  = xgetc(fi);

      int c;         -returned char or -1
      FILE *fi;      -file pointer

      xgets() gets a single character from a file pointer.  -1 is returned
      on EOF or error.


bool  = xputc(fi, c);

      int bool;      -did it work?
      FILE *fi;      -file pointer
      char c;        -character to write

      output a single character to a file.  NOTE: Since files are buffered,
      you may not get an error until the buffer is flushed.


actual = xread(fi, buf, n);

      int actual;    -actual bytes read or 0
      FILE *fi;      -file pointer
      char *buf;     -buffer to read into
      int n;         -max # bytes to read

      0 is returned on EOF or error.  Attempt to read n bytes into a buffer.
      The actual number read is returned.


bool = xwrite(fi, buf, n);

      int bool;      -did the operation work?
      FILE *fi;      -file pointer
      char *buf;     -buffer
      int n;         -bytes to write

      Note that xwrite() returns a bool, not the actual number bytes
      written.


bool = xflush(fi);

      int bool;      -sucess?
      FILE *fi;      -file ptr;

      FILE is returned only if the buffer was modified AND the Write()
      failed.


newpos = xseek(fi, offset, which);

      int newpos;    -NEW position AFTER xseek.
      FILE *fi;      -file pointer
      int offset;    -offset relative to 'which'
      int which;     -AMIGA conventions  -1(start)  0(current)  1(end)


pos    = xtell(fi);

      int pos;
      FILE *fi;

      Self evident: returns the current seek position.  Note that this
      may not reflect the actual Seek() position of the underlying file
      handle.


xclose(fi);

      FILE *fi;

      close the file pointer AND the underlying file handle.  You may pass
      this routine a NULL without ill-effects.



ptr   = gets(buf)

      char *ptr;
      char *buf;

      gets() uses Input() to get the next line from the programs STDIN.
      NULL is returned on EOF or error.

      This is rather a slow function, since data is read one-byte-at-a-time.
      It works fine for user-input, but if your program expects STDIN to
      be a file, you may want to xattach() Input() to a file-pointer and
      use xgets().


bool = puts(str)

      int bool;
      char *str;

      Output the \0 terminated string to STDOUT, replacing the \0 with
      a newline (\n).  Unlike AMIGA.LIB's puts(), this one allows
      strings of any size.


---------------------------------------------------------------------------

result   = atoi(str)

      int result;    -resulting integer
      char *str;     -source string

      atoi() converts ascii-decimal integers into integers, stopping at
      the first illegal character.


#include <xmisc.h>
bool     = openlibs(libs_mask)

      int bool;         -if all the libraries were openned
      int libs_mask;    -mask of all libraries to open.

      openlibs() is an easy way of openning several run-time libraries at
      once.  If you have this call in your code, global definitions for
      all of the amiga's standard libraries will be automatically
      included.  You specify a mask of libraries to open (see xmisc.h for
      mask #defines).  If all the libraries could be openned, TRUE is
      returned.  If one or more could not be openned, FALSE is returned on
      the ones that were able to be openned are closed.


closelibs(libs_mask)

      int libs_mask;

      close the specified libraries.  Only open libraries will be closed.
      Thus, you can say:  closelibs(-1); to close all the libraries.


bool = wildcmp(wild, name)

      int bool;
      char *wild;
      char *name;

      wildcmp() returns TRUE of the wildcard-name matches a normal
      string-name:

         TRUE = wildcmp("abcd?f", "abcdef");
         TRUE = wildcmp("abc*x",  "abcd.e.f.x");
         FALSE= wildcmp("ab??",   "ab");

      The wildcard name may consist of any number of '*'s and '?'s.


check32()
      Checks to see if the program was compiled using 32-bit ints.  If
      not, gives an error message and exit()'s.


io_open()
io_close()


  long
  io_open(device_name, unit, flags, &rreq, &wwreq, req_size, spec1, spec2)

    char *device_name          -the device name (ex: "serial.device")
    int   unit                 -unit #
    int   flags                -OpenDevice flags
    struct IOxxxxxx *rreq      -address of pointer (will be filled in)
    struct IOxxxxxx *wreq      -address of pointer (will be filled in)
    int   req_size             -size of above structures
    long  spec1,spec2          -special arguments for preinitialization
                                 (depends on the device your openning)

    EXAMPLE:
    ----------------------
    typedef struct IOExtSer SIO;

    #define SERFLAGS (SERF_XDISABLED | SERF_SHARED)
    SIO *srr, *swr;
    long mask;

    mask = io_open("serial.device",0,0,&srr,&swr,sizeof(SIO),SERFLAGS,0);
                   ...
    io_close(srr, swr, sizeof(SIO));

    ----------------------

    The structure for rreq and wreq depend on the device you are openning.
    You must be sure to specify the correct size.

    Some devices, such as the serial device, require certain fields inside
    their IO structures to be initialized before the OpenDevice().  Since
    io_open() Allocates these structures for you, these extra parameters
    must be passed to io_open() via SPEC1 and SPEC2 in the arguments list
    as outlined below:
                     SPEC1              SPEC2
    console.device   window pointer     window structure size
    parallel.device  parallel flags     0
    serial.device    serial flags       0
    **ALL OTHERS**   0                  0

    note on audio device:  You must ADCMD_ALLOCATE and ADCMD_FREE
    manually.

    You also pass io_open() the address of two pointers (e.g. **x).  These
    will be filled in by io_open() to result in a READ and WRITE request
    structure, each with it's own reply port, and with it's io_Command
    fields initialized to CMD_READ and CMD_WRITE, respectively.  You may
    specify a NULL for the **WRITE request structure instead of a
    **wreq.  This will result in only a READ request structure being
    set up.

    You do not have to use the structures for only CMD_READ and CMD_WRITE,
    of course, you can use them for any io command.

    a signal MASK with one bit set is returned.  This is the signal bit
    for the read-request structure (if rreq was NULL, then it is the
    signal for the write-request structure).  an example mask:
     00000000001000000000000000000000 in binary.

    0 is returned if the open fails.


  io_close(rreq, wreq, size)

       specify 0 for the wreq if it doesn't exist (e.g. you passed a
       NULL for it in the io_open() ).




----------------------------------------------------------------------------
memory routines.  These are not quite automatic.  You must call the
routine 'free_memory()' just before you exit if you use 'malloc'.
The binary-zero/set/mov routines are written in assembly for speed.


ptr = malloc(bytes);

   char *ptr;        -pointer to buffer
   int bytes;        -#bytes to allocate

   NULL is returned if the allocation failed.  The pointer returned is on
   32-bit boundries (e.g. longword).


free(ptr)

   char *ptr;

   Free a malloc'd space.  Call only with pointer's you have
   malloc'd.


free_memory()

   Must be called before you exit to free ALL mallocs that have occured .


bzero(s, n)

   char *s;
   int n;

   Zero n bytes starting at s.


bset(s, n, v)

   char *s;    -start address
   int n;      -# bytes
   int v;      -fill value

   Set a memory area to 'v'.


bmov(s, d, n)

   char *s;    -source
   char *d;    -dest
   int n;      -# bytes

   Move from source to destination. bmov() will properly do a forward or
   reverse move depending on where s and d are relative to each other.


--------------------------------------------------------------------------
String routines.  Exactly as normal STDIO routines.


len   = strlen(str)

   int len;
   char *str;

   return the length of the string.


dest = strcpy(dest, source)

   char *source, *dest;

   string copy.  source and destination must be disjunct.


dest = strncpy(dest, source, maxchars)

   char *dest, *source;
   int maxchars;

   Copy no more than maxchars bytes.  This does NOT include the \0.


dest = strcat(dest, source)

   Place the source after the destination.  Source and where source will
   be placed on destination must be disjuct.


dest = strncat(dest, source, n)

   Same as strcat, but no more than n chars will be copied, \0 NOT included.


result = strcmp(source, dest)

   Compare the source with the destination.  Result is:

   -1    source < dest
   0     source = dest
   1     source > dest


result = strncmp(source, dest, n)

   Same as strcmp, but a maximum of n chars are compared.