CP/M

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

/ CP/M / CPM_CDROM.iso / lambda / soundpot / p / sclib2.lbr / CLIB.DZC / CLIB.DOC

Wrap

Text File | 1993-10-25 | 14.5 KB | 475 lines

CLIB.DOC by F. A. Scacchitti 25 Glenview Lane Rochester, NY 14609 11 - 24 - 84 Thi≤á 'Cº Librar∙ contain≤ mos⌠ oµ thσ function≤ describeΣ iεá J« ì E«á Hendrix'≤á "Thσ Small-├ Handbook"«á Thesσ function≤ arσá als∩ ì describeΣ iε thσ Ma∙ 198┤ Dr«á Dobb'≤ Journal«á M∙ intent¼á a≤ i≤ ì his¼áá i≤á t∩á providσá ßá completσá standarΣá librar∙á followinτ ì specication≤á describeΣá iε "Thσ ├á Programminτá Language"«á Thi≤ ì librar∙á i≤á ßá combinatioε oµ module≤á obtaineΣá froφá Hendrix'≤ ì library¼á ßá modifieΣá publiπ domaiε runtimσ librar∙ anΣá module≤ ì writteεá b∙á myself«á Thσá followinτá sourcσá file≤á contaiεá thσ ì function≤ describeΣ iε thi≤ document: ABORT .MAC ABS .C ATOI .C ATOIB .C AVAIL .C BDOS .MAC CALL1 .MAC CALL2 .MAC CALL3 .MAC CALL4 .MAC CALL5. .MAC CALLOC .C CLEARERR.C CPMDISK .MAC CPMIO .MAC CSEEK .C CTELL .C CTELLC .C DELAY .MAC DOLDDR .MAC DOLDIR .MAC DTOI .C FEOF .C FERROR .C FFLUSH .C FGETC .MAC FGETS .MAC FILELIB .C FPRINTF .C FPUTC .MAC FPUTS .MAC FREAD .C FREBUF .C FREE .C FREEIO .MAC FSCANF .C FWRITE .C GETCHAR .C GETCHX .C GETS .MAC GRABIO .MAC GRABUF .C INP .MAC ISALNUM .C ISALPHA .C ISASCII .C ISATTY .C ISCNTRL .C ISDIGIT .C ISGRAPH .C ISLOWER .C ISPRINT .C ISPUNCT .C ISSPACE .C ISUPPER .C ISXDIGIT.C ITOA .C ITOAB .C ITOD .C ITOO .C ITOU .C ITOX .C LEFT .C LEXCMP .C LIBID .C MALLOC .C MAX .C MIN .C OTOI .C OUTP .MAC PAD .C POLL .C PRNTF .C PUTCHAR .C PUTLIST .MAC PUTS .C READ .C RENAME .C REVERSE .C REWIND .C SIGN .C STRCAT .C STRCHR .C STRCMP .C STRCPY .C STRLEN .C STRNCAT .C STRNCMP .C STRNCPY .C STRRCHR .C TOASCII .C TOLOWER .C TOPOFMEM.MAC TOUPPER .C UALLOC .C ULINK .C UNGETC .C UNLINK .MAC UTOI .C WRITE .C XTOI .C ZZBUF .MAC ZZFIO .MAC èRathe≥á thaεá tryinτ t∩ providσ ß Unix-likσ environmen⌠ (anΣá thσ ì resultinτá overhead)¼á I'vσ attempteΣ t∩ pu⌠ ßá packagσá togethe≥ ì whicΦá i≤á morσ conducivσ to CP/M«á Thi≤ Librar∙ i≤á designeΣá t∩ ì producσá minimuφá sizσ file≤ whilσ retaininτ thσ flavo≥á oµá 'C'« ì Man∙á oµá thσá function≤ arσ writteε iε assemble≥á and¼á a≤á timσ ì permits¼á morσá function≤á wil∞ bσ optimizeΣ fo≥á botΦá sizσá anΣ ì speed«á Mos⌠ function≤ containeΣ iε thi≤ librar∙ arσ useablσ witΦ ì an∙ CP/═ 8░ system¼á however¼á man∙ oµ thσ I/╧ function≤ interac⌠ ì witΦ eacΦ othe≥ a≤ wel∞ a≤ thσ runtimσ routines«á Anyonσ adaptinτ ì an∙á portion≤ oµ thi≤ librar∙ shoulΣ evaluatσ thσ sourcσ codσá oµ ì thσ particula≥ module(s⌐ iε question« A≤ witΦ al∞ libraries¼ itsº ì valuσá manifest≤ itselµ wheε useΣ witΦ ß linking-loade≥ tha⌠á ha≤ ì searcΦ capabilities« (eg« Microsoft≤ M80/L80/LIB8░ package) .pa èFEATURES OF THE LIBRARY 104 function≤ (5 aliases⌐ arσ available¼á includinτ mos⌠ standarΣ ì 'Cº functions. Smalle≥á prograφá sizσ thaε mos⌠ - minimuφ prograφá sizσá i≤á 25╢ ì bytes. This would be the result of the following 'C' code. #include <stdio.h> main() { } Argπ anΣ arg÷ arσ handleΣ b∙ thσ runtimσ modulσ anΣ alway≤ passeΣ ì t∩ thσ use≥ program« ┴ maximuφ oµ 2┤ argument≤ ma∙ bσ passeΣ witΦ ì 23 availablσ t∩ the user. File≤ ma∙ bσ openeΣ iε read¼á writσ o≥ appenΣá modes«á Read/writσ ì (+⌐ mode≤ arσ no⌠ supported. All I/O buffers are allocated outside program space including: 1 128 byte default disk I/O buffer 8 1 K byte file buffers (available for general use) Thσá defaul⌠ disδ I/╧ buffe≥ i≤ se⌠ b∙ thσ runtimσ modulσ t∩ ì preservσ thσ content≤ oµ thσ ruε strinτ residinτ a⌠ thσ CP/═ ì defaul⌠á buffer«áá Thσá standarΣá defaul⌠á buffe≥á (80h⌐á i≤ ì restoreΣ a⌠ prograφ completion. Thσáá ╕á filσá buffer≤á arσá automaticall∙áá allocateΣáá anΣ ì deallocateΣá b∙á thσá filσ handlinτ routine≤á anΣá thσá use≥ ì needn'⌠ worr∙ abou⌠ sequence« However¼ thesσ buffer≤ arσ no⌠ ì restricteΣá t∩á filσá I/O«á The∙ ma∙ bσá allocateΣá vißá thσ ì grabuf(⌐ functioε anΣ deallocateΣ viß frebuf()« Cautioε mus⌠ ì bσá useΣá t∩ insurσ tha⌠ an∙ usσ oµ thesσ buffer≤á doe≤á no⌠ ì exceeΣá thσ ▒ K-bytσ limit«á Thσ result≤ oµ failinτ t∩á sta∙ ì withiε thσ limit≤ i≤ unpredictable. Sequentia∞ááá dynamiπáá memor∙áá allocation/deallocatioεáá schemσ ì (calloc,malloc¼á anΣá free⌐ start≤ a⌠ thσ enΣ oµ thσ las⌠á buffe≥ ì anΣá end≤ a⌠ thσ stack«á Thσ use≥ mus⌠ maintaiε thσ integrit∙á oµ ì thi≤á area«á Iµá ßá buffe≥ i≤ se⌠ freσ belo≈ onσ tha⌠á shoulΣá bσ ì maintained, thσá schemßá wil∞á indicatσá al∞á memor∙á abovσá anΣ ì includinτ thσ releaseΣ buffe≥ i≤ available«á Allocatinτ anΣ usinτ ì anothe≥ buffe≥ a⌠ thi≤ poin⌠ ma∙ undesirabl∙ wipσ ou⌠ datßá whicΦ ì should have been maintained. Optionall∙á eliminatσá thσá warφá boo⌠á tha⌠á occur≤á oεá prograφ ì termination«á Thi≤á i≤ accomplisheΣ in the following manner: Defininτá thσ globa∞ ZZZCC╨ ╜ ░ place≤ thσ stacδ a⌠ thσ basσ ì oµ thσ BDO╙ anΣ return≤ viß warφ boo⌠. (jmp 0) Defininτ thσ globa∞ ZZZCC╨ ╜ ▒ place≤ thσ stacδ a⌠ thσá basσ ìè oµ thσ CC╨ anΣ return≤ t∩ thσ CCP. ZZZCC╨ ma∙ bσ generateΣ a≤ ß compile≥ functioε viß ß switch¼ ì o≥ addeΣ a≤ thσ followinτ inlinσ codσ t∩ ß prograφ o≥ heade≥ ì file. #asm zzzccp:: db 1 #endasm Iµá lef⌠ undefineΣ i⌠ wil∞ defaul⌠ t∩ warφ boot«á Thσ linke≥ ì wil∞ indicatσ i⌠ a≤ undefined¼ witΦ n∩ consequence« CP/═á integrit∙ i≤ maintaineΣ b∙ thσ runtimσ modulσ anΣá restoreΣ ì a⌠á prograφ completion«á Also¼á al∞ opeε file≤á arσá closed¼á bu⌠ ì buffers are NOT flushed. prntf(⌐ i≤ ß specia∞ versioε oµ printµ whicΦ onl∙ support≤ thσ d¼ ì c¼á anΣ ≤ specifications« FielΣ lengtΦ specifier≤ (wheε used⌐ arσ ì limiteΣ t∩ ß sizσ oµ ╣ anΣ fielΣ separato≥ specification≤á aren'⌠ ì alloweΣ anΣ shoulΣ no⌠ bσ used« Thi≤ modulσ occupie≤ 82╕ byte≤ oµ ì codσ space. getchx(⌐á i≤á ßá specia∞ versioε oµ getchar(⌐ whicΦá use≤á direc⌠ ì consolσ inpu⌠ rathe≥ thaε thσ standarΣ consolσ input« I⌠ doe≤ no⌠ ì reflec⌠á character≤á t∩á thσá screeε o≥á tra≡á thσá CP/═á contro∞ ì characters. grabuf(⌐á anΣá frebuf(⌐ allo≈ thσ use≥ acces≤ t∩ ß selµá managinτ ì memor∙ allocatioε scheme«á EacΦ buffe≥ returneΣ b∙ grabuf(⌐ i≤ 1╦ ì byte≤ oµ memor∙ anΣ shoulΣ no⌠ bσ exceeded«á AlthougΦ thi≤á isn'⌠ ì standard¼á i⌠á doe≤ providσ ß somewha⌠ bomΓ resistan⌠ (no⌠ proof⌐ ì memory alloc./dealloc. schema along with the standards. .pa èFUNCTIONS IN THE LIBRARY Onl∙á thσá function≤ no⌠ describeΣ iεá J«á E«á Hendrix'≤á Small-├ ì Manua∞, or those that differ from his, wil∞ bσ described. abort(code) exit≤á thσá prograφá displayinτ thσá "Abortedóá messagσá anΣ ì optiona∞á codσá passeΣ b∙ thσ user«á Iµ n∩ codσ i≤ passeΣá ß ì default code of control g (bell) is used. abs(nbr) int nbr atoi(str) char *str atoib(str,base) char *str; int base; avail(abort) int abort; bdos(fn,data) int fn, data; standarΣ CP/═ bdo≤ cal∞ fε i≤ thσ functioε codσ anΣ datßá i≤ ì thσá settinτ oµ thσ dσ register«á Return≤ whateve≥ thσá cal∞ ì places in the accumulator. calloc(nbr,sz) int nbr, sz; cfree(addr) char *addr; clearerr(fd) int fd; cpm(fn,data) same as bdos(fn,data) cpmdisk(nbr) int nbr; log in disk number nbr. cseek(fd,offset,mode) ctell(fd) int fd; ctellc(fd) int fd; delay(n) int n; dela∙á fo≥á εá millisecond≤, baseΣ oε ßá ┤á Mh·á clocδá (25░ ì nanoseconΣ cyclσ time). delete(name) char *name; dolddr(source, destination, n) int source, destination, n; perform z80 lddr instruction. doldir(source, destination, n) int source, destination, n; perform z80 ldir instruction dtoi(decstr, nbr) char *decstr; int nbr; èexit(code) exit(); exits program and returns to CP/M fcb(fd,name) char *name; int fd; construct a file fcb on file name at location fd. (located in filelib module) fclose(fd) int fd; (located in file lib module) feof(fd) int fd; ferror(fd) int fd; fflush(fd) int fd; fgetc(fd) int fd; fgets(str, sz, fd) char *str; int sz, fd; fopen(filename, mode) char *name, mode; (locateΣ iε fileliΓ modulσ - onl∙ r¼ w¼ anΣ ß mode≤ ) fprintf(fd, format[, arg1, ar2,...]) int fd; char *format; fputc(c, fd) char c; int fd; fputs(str, fd) char *str; int fd; fread(buffer, sz, n, fd) char *buffer; int fd, n, sz; frebuf(buff) int buff; freσá thσá buffe≥á bufµ allocateΣ b∙ grabuf(⌐á anΣá makσá i⌠ ì available for use. free(addr) same as cfree(addr) freeio(fd) int fd; freσá thσá filσ structurσ allocateΣ b∙ grabio(⌐ anΣ makσá i⌠ ì available for use. fscanf(fd, format, arg, arg, . . . ) fwrite(buff, sz, n, fd) char *buf; int sz, n, fd; getc(fd) same as fgetc(fd) getchar() getchx(⌐ i≤ ß specia∞ versioε oµ getchar(⌐ whicΦ use≤ direc⌠á consolσ ì inpu⌠á rathe≥ thaε thσ standarΣ consolσ input«á I⌠ doe≤á no⌠ ì reflec⌠á character≤á t∩ thσ screeε o≥ tra≡ thσ CP/═á contro∞ ì characters. ègets(str) char *str; grabio() return≤á thσá addres≤á oµá thσá firs⌠á availablσá filσáá I/╧ ì structure. If none is available NULL is returned. grabuf() return≤á thσá addres≤ oµ thσ firs⌠ availablσ buffe≥á iεá thσ ì file I/O structure. If none is available NULL is returned. inp(nbr) int nbr; returns the value read in at port nbr isalnum(c) char c; isalpha(c) char c; isascii(c) char c; isatty(fd) int fd; iscntrl(c) char c; isdigit(c) char c; isgraph(c) char c; islower(c) char c; isprint(c) char c; ispunct(c) char c; isspace(c) char c; isupper(c) char c; isxdigit(c) char c; itoa(nbr, str) int nbr; char *str; itoab(nbr, str, base) int nbr, base; char *str; itod(nbr, str, sz) int nbr,sz; char *str; itoo(nbr,str,sz) int nbr,sz; char *str; itou(nbr,str,sz) int nbr,sz; char *str; itox(nbr,str,sz) int nbr,sz; char *str; left(str) char *str; lexcmp(str1, str2) char *str1, *str2; èlibid() displays the date and originator of this library malloc(sz) int sz; max(a, b) int a, b; returns the greater of a or b min(a, b) int a, b; returns the lesser of a or b otoi(str,nbr) char *str; int nbr; outp(nbr,data) int nbr, data; transmits data out of port nbr. pad(dest, ch, n) char *dest, *n; int ch; poll(pause) int pause; printf(format[,arg1,arg2,...]) prntf(format[,arg1,arg2,...]) i≤ ß specia∞ versioε oµ printµ whicΦ onl∙ support≤ thσ d¼ c¼ ì anΣá ≤ specifications«á FielΣ lengtΦ specifier≤ (wheεá used⌐ ì arσáá limiteΣáá t∩á ßá sizσá oµá ╣áá anΣáá fielΣáá separato≥ ì specification≤á aren'⌠ alloweΣ anΣ shoulΣ no⌠ bσ used« putc(c, fd) same as fputc(c, fd) putchar(c) char c; putlist(c) char c; outputs character c to the list device. puts(str) char *str; read(fd, buff, n) int fd, n; char *buff rename(old,new) char *old, *new; reverse(str) char *str; rewind(fd) int fd; scanf(format, arg1, arg2, . . .) sign(nbr) int nbr; strcat(dest, sour) char *dest, *sour; strchr(str, c) char *str, c; strcmp(str1, str2) char *str1, *str2; èstrcpy(dest, sour) char *dest, *sour; strlen(str) char *str; strncat(dest, sour, n) char *dest, *sour; int n; strncmp(str1, str2, n) char *str1, *str2; int n; strncpy(dest, sour, n) char *dest, *sour; int n; strrchr(str, c) char *str, c; toascii(c) char c; tolower(c) char c; topofmem() returns base of system bdos toupper(c) char c; ualloc(n, clear) char *n; int clear; ungetc(c, fd) char c; int fd; unlink(name) same as delete(name) utoi(str, nbr) char *str; int nbr; write(fd,buffer,n) int fd, n; char *buffer; xtoi()(str, nbr) char *str; int nbr; .pa èLIBRARY STRUCTURE Thσá clib.re∞á Small-C systeφ librar∙ module≤ arσ loadeΣá iεá thσ ì followinτ sequencσ t∩ avoiΣ backwarΣ referencinτ b∙ L80: ULINK** LIBID* UNGETC RENAME FREAD READ FWRITE WRITE FFLUSH REWIND CSEEK CTELL CTELLC FILELIB GRABUF* GRABIO* FREBUF* FREEIO* FPRINTF FSCANF PRNTF* FPUTS FGETS GETS PUTS FPUTC FGETC PUTCHAR GETCHAR GETCHX* CPMIO* CPMDISK* PUTLIST* CALLOC MALLOC UALLOC* AVAIL* FREE POLL* ABS ATOI ATOIB DTOI ISALNUM ISALPHA ISASCII ISATTY ISCNTRL ISDIGIT ISGRAPH ISLOWER ISPRINT ISPUNCT ISSPACE ISUPPER ISXDIGIT ITOA ITOAB ITOD ITOO ITOU ITOX LEFT LEXCMP OTOI REVERSE SIGN STRCAT STRCHR STRCMP STRCPY STRLEN STRNCAT STRNCMP STRNCPY STRRCHR TOASCII TOLOWER TOUPPER UTOI XTOI PAD FEOF FERROR CLEARERR DELAY* DOLDDR* DOLDIR* INP* OUTP* TOPOFMEM* UNLINK MIN* MAX* CALL1** CALL2** CALL3** CALL4** CALL5** BDOS* ABORT ZZFIO** ZZBUF** * indicates a non standard function ** indicates a system function SYSTEM MODULES Refe≥á t∩á thσá sourcσ file≤ oµ thesσ module≤á fo≥á morσá detail≤ ì regarding operation. ULIN╦á (25▒ bytes⌐ contain≤ thσ routine≤ t∩ stee≥ thσ 'Cº prograφ ì froφ CP/═ t∩ thσ use≥ prograφ anΣ bacδ agaiε t∩ CP/M« Thi≤ modulσ ì i≤ thσ onl∙ onσ iε thσ librar∙ t∩ havσ aε entr∙ poin⌠ defineΣá a≤ ì ß startinτ point¼ thereforσ thσ prograφ wil∞ alway≤ star⌠ here« CALL▒á (3▓á bytes⌐á contain≤á thσ codσ t∩á suppor⌠á thσá multipl∙ ì operator. ( * ) CALL▓á (9┤á bytes⌐á contain≤á thσá codσá t∩á suppor⌠á thσá dividσ ì and modulus operators. ( / % ) è CALL│á (2╢á bytes⌐á contain≤á thσá codσá t∩á suppor⌠á thσá switcΦ ì statement. CALL┤ (2▒ bytes⌐ contain≤ thσ codσ t∩ suppor⌠ thσ righ⌠ anΣá lef⌠ ì shif⌠ operators. ( >> << ) CALL╡á (23╡á bytes⌐á contain≤á thσá codσá t∩á suppor⌠á al∞á othe≥ ì arithmetiπá anΣá logica∞ operator≤ a≤ wel∞ a≤ memor∙ anΣá addres≤ ì fetch and store operations. ZZFI╧á (23á bytes⌐ contain≤ storagσ fo≥ globa∞ variable≤ useΣá b∙ ì file I/O and fgetc, fputc, etc . . . ZZBU╞á (▒ byte⌐ i≤ thσ las⌠ modulσ iε thσ librar∙ anΣá serve≤á t∩ ì marδá thσá startinτ poin⌠ fo≥ I/╧ buffer≤ anΣ thσ dynamiπá memor∙ ì allocation scheme.