The Fred Fish Collection 1.5

home *** CD-ROM | disk | FTP | other *** search

/ The Fred Fish Collection 1.5 / ffcollection-1-5-1992-11.iso / ff_progs / prog_c / mylib.lzh / MY.LIB / DOC.TXT next >

Wrap

Text File | 1991-11-01 | 18.9 KB | 619 lines

MY.LIB COMPILATION - 32 bit Lattice C OR 32 bit Manx C (i.e. +l option) It has not been tested under Manx, but since the assembly routines do not use the frame pointer (Lattice and Manx use different FP's), I see no problems. - Compile Each .C module with stack checking DISABLED (this is an option with lattice, I don't know about manx) - Assemble each .ASM module - JOIN ALL the .O modules together to create the library. Under MANX, you might have to use Manx's support programs to create the library. - When linking in MY.LIB, link it BEFORE Amiga.lib. It can go before or after any other libraries, but remember that if MY.LIB has priority (comes before) LC.LIB, some of LC.LIB's functions are replaced (string functions, etc...). Additionaly, MY.LIB contains the function FPRINTF for FILEHANDLES (the fprintf in LC.LIB and MAnx's library is for the respective STDIO routines). Also read the docs on malloc() and free() under MY.LIB MY.LIB DOCUMENTATION OF COMMANDS: XSTDIO: fi = xopen(name, mode, bufsize) result = xasync(fi, command) xclose(fi) c = xgetc(fi) xputc(fi, c) actual = xread(fi, buf, n) bool = xwrite(fi, buf, n) bool = xsetbuf(fi, bufsize) fi = xattach(FileHandle, bufsize) fh = xdetach(fi) position = xtell(fi) newpos = xseek(fi, offset, mode) mode= -1/0/1 bool = xputs(fi, buf) Note: adds \n nchars = xgets(fi, buf, max) Replaces \n with \0. nchars includes \0 buf = gets(buf) puts(buf) bool = xflush(fi) xprintf(fi, ctlstring, args...) xstdio file pointer fprintf(fh, ctlstring, args...) AmigaDos file handle STRING: len = strlen(str) dst = strcpy(dst, src) dst = strcat(dst, src) result = strcmp(s1, s2) result: -1 s1<s2 0 s1=s2 1 s1>s2 dst = strncpy(dst, src, max) max doesn't include \0 dst = strncat(dst, src, max) max doesn't include \0 dst = strncmp(dst, src, max) MEMORY: str = malloc(bytes) (a hack.. is wasteful) free(str) free_memory() must be called on exit if you use malloc(). bzero(ptr, bytes) bmov(src, dst, bytes) handles both src<dst and src>dst bset(ptr, bytes, char) MISC: val = atoi(str) bool = openlibs(mask) see xmisc.h for bitmap of mask closelibs(mask) may give argument '-1' to close all bool = wildcmp(wild, name) check32() exits if not compiled w/32 bit ints io_open() See below for calling parameters io_close() See below for calling parameters bool = checkbreak() check if break pressed resetbreak() reset 'break-pressed' signal. mountrequest(bool) disable/enable requestors for unmounted filing system accesses. CAPSULE SUMMARY OF XSTDIO: The xstdio routines provide the programmer (read 'us') with buffered and asyncronous file support. With xstdio, you generally have better control over your file-pointers than the original stdio. The disadvantage to xstdio is that its error reporting mechanism hasn't been fully developed as yet. Please note that the xstdio file pointers (I denote them as 'FI') are not in anyway compatible with stdio file pointers. For your safety, you should not access an xstdio file pointer's file handle directly. Especially when you are using the asyncronous write utility (see xasync()), the file pointer's file handle is placed in a precarious position and should only be accessed through xstdio routines. 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. Implimentation Notes: My implimentation of xprintf() and fprintf() uses the stack to hold the output buffer... 256 bytes. Therefore, the eventual output string of a given xprintf() or fprintf() call cannot be larger than 255 bytes. I've heard that it can't be larger anyway due to restrictions on RawDoFmt(), but am not sure. The xstdio puts() exists to correct a problem with AMIGA.LIB's puts(). Namely, the latter crashes on outputs larger than 255 bytes for no good reason. -------------------------------------------------------------------------- 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. xprintf(fi, cs, arg, arg ... ) FILE *fi; char *cs; Uses AMIGA.LIB's RawDoFmt. This version of printf outputs to a file pointer. xprintf() dies with large output strings (>255), so don't be too fancy. Also note that RawDoFmt is not a full fledged printf, but should do what you want. fprintf(fh, cs, arg, arg ... ) long fh; char *cs; Same thing as xprintf() except works on AmigaDos File Handles. 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. checkbreak() resetbreak() checkbreak() returns true (1) if ^C has been pressed. Once ^C has been pressed, checkbreak() will always return true until you call resetbreak() to reset the signal. (checkbreak() does not reset the signal). mountrequest(bool) turn on or off automatic system requestors when your program accesses unmounted prefixes: TRUE (default) -system will prompt user to place correct disk in drive via a requestor when program accesses unmounted file. FALSE -if a given file path is not mounted, an error is returned to the program rather than prompting the user. WARNING: Do not exit the program while mountrequest() is set to FALSE... bad things might happen. NOTE: You can call mountrequest() with it's current state without harm. That is, you can call mountrequest(TRUE) when it is already TRUE, and mountrequest(FALSE) when it is already false. 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.