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.