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.