ftp.barnyard.co.uk

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

/ ftp.barnyard.co.uk / 2015.02.ftp.barnyard.co.uk.tar / ftp.barnyard.co.uk / cpm / walnut-creek-CDROM / JSAGE / ZSUS / PROGPACK / SCZ01BET.LBR / -CLIB01.ZZZ / -CLIB01.

Wrap

Text File | 1989-05-24 | 15KB | 536 lines

SmallC/Z 05/08/89 This is a list of modules and routine names in CLIB. Short documentation on function and calling arguments for some is included. Descriptions of the more standard C functions and many very low level internal routines are for the time being omitted. Hopefully, as time allows, they can be added. Most or all significantly new or different code has associated descriptions. While this may not be the most convenient possible format (as opposed to by alphabetical order or by functionality) of documentation, it was easier for me to construct and keep track of, and offers the other advantage that you can easily tell which routines are grouped in which modules. This way, you'll know, when you use a function which ones you get "free", i.e. without increase in program size. Note that routine names that begin with "U" are in almost all cases runtime system routines, typically intended for calls from assembler. The phrase "Intended for calls from assembler" mainly means that arguments are being passed in registers, rather than on the stack. The phrase "Intended for calls from C" means the reverse, and certainly doesn't preclude calls from assembler. There are sometimes alternate entry points into routines. The full names are given. If you're using M80/L80 format (as opposed to SLR), bear in mind that extrnals and entries are truncated to six characters. Last checked against SLRLIB module map: 04/30/89. copyright (c) Al Grabauskas, 1989 ------------------------------------------------------------------------------- UENTRY ------- UENTRY Uentry saves the o/s value of HL and the return to o/s pointer, then walks through entry vector Uinvec, emulating calls to those routines. entered through initial jump in assembler configuration header. ------- UNULRTN Unultrn null routine (a single "ret" assembler instruction). Used to disable pointer based routines in entry and exit vectors like user exit traps. ------- URETCPM Uretcpm routine to return to the o/s without a warmboot, using the return to o/s pointer saved by Uentry (above). entered through Usysret pointer in the exit vector if setwbt() has not been executed to set warm boot on. UEXCD ------- UEXCD Uexcd vanilla cp/m exit code interpreter. calls standard runtime exit code message function sysexcod(), then then returns. Called by exit() as it walks the exit vector through Usetecd pointer. SYSEXCOD ------- SYSEXCOD sysexcod() runtime system exit code interpreter. sends a message to the console if the code passed to exit() was a runtime function termination code as defined in sysexits.h #include file. Called by Uexcd routine (from both CLIB and CZVLIB). USYSINIT ------- USYSINIT Usysinit initializes the cp/m environment in a SmallC/Z program. Primarily a null routine. Called by Uentry as it walks the initilization vector. CSYSLIB ------- UADVANCE ------- UCLREOF ------- UCONIN ------- UCONOUT ------- UDEFUSER ------- UDIRTST ------- UFBDOS ------- UFIELD ------- UGETSEC ------- UIOEXIT ------- ULOADFN ------- UMAIN ------- UMODE ------- UNEWFCB ------- UNEXTC ------- UOPEN ------- UPARSE ------- UPUTSEC ------- UREAD ------- UREDIREC ------- USECTOR ------- USETEOF ------- USETERR ------- USTATUS ------- UWRITE Description of this module as a whole: This module contains the basic runtime support code for SmallC/Z. Note: it would be good to segregate the i/o primitives here into separate module for purposes of making them independent of the rest of the runtime code. also need a list of the primitive names used by the runtime, so that a replacement i/o package would be able to satisfy the needs of the runtime. SETXTRAP ------- SETXTRAP setxtrap(ptr) int *ptr; sets the user exit trap vector Uextrap to point at routine specified by ptr (pointer to function, actually). If ptr is NULL, sets user exit trap vector to point at Unulrtn. Intended for calls from C. No meaningful return value. SETWBT ------- SETWBT setwbt() sets return to o/s exit vector Usysret to 0, effectively causing a warm boot to take place at program termination. Intended for calls from C. No meaningful return value. AUXBUF ------- AUXBUF ------- UXFLUSH ------- UXINIT ------- UXREAD ------- UXWRITE BDOS ------- BDOS bdos(funct,arg) corresponds to bdos((bc),(de)) int funct, arg; BOTH ARGUMENTS MUST BE SPECIFIED. Intended for calls from C. BDOS errors are returned as -1. BIOS ------- BIOS bios(funct,arg1,arg2) corresponds to bios(func,(bc),(de)) int funct, arg1, arg2; ALL 3 ARGUMENTS MUST BE SPECIFIED, even tho the last is used only by SELDSK and SECTRAN. Intended for calls from C. BIOS return value. PUTS ------- PUTS FGETS ------- FGETS ------- GETS ------- UGETS FPRINTF ------- FPRINTF ------- PRINTF ------- UGETS FPUTS ------- FPUTS PUTCHAR ------- PUTCHAR FPUTC ------- FPUTC ------- PUTC FREAD ------- FREAD ------- READ FREOPEN ------- FREOPEN FSCANF ------- FSCANF ------- SCANF ------- USCAN FWRITE ------- FWRITE ------- WRITE GETCHAR ------- GETCHAR PAD ------- PAD ------- STRINIT POLL ------- POLL RENAME ------- RENAME REWIND ------- REWIND ABS ------- ABS ATOI ------- ATOI ATOIB ------- ATOIB MRELEASE ------- MRELEASE mrelease(bp,x,f) int *bp, *x, f; releases core that would normally not be considered for dynamic allocation purposes to the free chain. you can use it to release the ccp or parts of a program used only once to the dynamic allocation kernel routines. you MUST be using the newer and larger memory routines (which are now defaulted in CLIB). if you release all or part of the ccp, it is your responsibility to use setwbt() (set warm boot on). if you omit this, unpredicatble things may occur on exit from your program. you should NOT use this to free core that is or was already part of the memory considered for dynamic allocation. usage: mrelease(bp,x,f); where: bp is a pointer to base of memory to free. an integer size will be placed here, and the pointer bumped up by two. see ualcfre module for the reasoning. x either a size (integer), or a pointer to end of memory to free (byte past, not inclusive). f true if x is a size, false if a ptr. No meaningful value returned. XALCFRE ------- XAINIT ------- XALLOC ------- XFREE Description of module as a whole: Routines to allow using the low level allocation primitives in the UALCFRE module to subdivide core within a block allocated from global core. These routines allow you to control memory fragmentation to any extent you desire, by letting you use the same memory allocation primitives used by the runtime within a block of core allocated to you. You can nest this type of usage to any depth you desire, can think of a reason for, and feel like keeping track of. usage: block=malloc(blksize); xainit(block); while (whatever) { . xaptr=xalloc(block,reqsize); . xfree(block,xaptr); . } The global block can be freed to global memory at any time using the standard free() function, but bear in mind that this will invalidate any pointers you have into it, since that causes it to be considered for further malloc() and calloc() requests. xainit(bp) int *bp; Initializes a previously allocated block for "in-block" memory management routines xfree() and xalloc(). This initialization consists of setting up control information analogous to that for global memory management in the block, so that xfree() and xalloc() can then parcel out requests from within it. xainit() leaves the first word in the block alone. This allows freeing and reallocating (in certain ways), without trashing the in-block memory status. The caller can use that word for chaining such blocks, etc. It is left somewhat open. Intended for calls from C. returns HL=pointer passed to it (bp, above) if successful, HL=0 otherwise (block too small for control info) xalloc(bp,size) int *bp, size; Allocates "size" bytes from the globally allocated block pointed to by bp. That block should already be initialized using xainit(). (under certain circumstances xalloc is smart enough to take care of this itself, but you shouldn't depend on that). Intended for calls from C. returns HL=pointer to satisfied request if successful, HL=0 otherwise xfree(bp,fp) int *bp, *fp; Frees the memory pointed to by fp back into the block pointed to by bp. That memory should have been allocated from that block to begin with, or VERY unpredictable results can occur. Intended for calls from C. No meaningful return code. UALCFRE ------- UALLOC ------- UFREE ------- UMEMINIT Description of module as a whole: This module contains the primitive operations for the new SmallC/Z memory management scheme. These routines are called by calloc(), malloc(), and free(), as well as by the routines in the XALCFRE and MRELEASE modules, and potentially other routines in the runtime support code. These routines work very well, but what they are doing is managing a fairly complex data structure which must not be corrupted by code going out of the bounds of memory allocated to it. With that caveat in mind, these routines (as opposed to the original Small-C memory management functions still available in the separate module SMALLALC) provide the ability to build arbitrarily complex data structures within the limitations of available memory with relative ease. Ualloc(size,initflag) int size, initflag; Allocates "size" bytes from memory pool described by global variables as shown in diagram in other documentation. Allocates from the current free memory chain in a best fit, closest to top of memory fashion. Retains size word in the two bytes just preceeding the pointer returned to the user for later use by Ufree(). Not corrupting the size word is the responsibility of the programmer. Initializes allocated node to zeroes if initflag is true. Intended for calls from C. returns HL=pointer to allocated memory if successful, HL=0 otherwise Ufree(ptr) char ptr; Frees block previously allcated using Ualloc() to current free memory chain, defragmenting as necessary. Obviously assumes a valid memory management data structure (i.e., size word of node to free has not been corrupted, no other parts of free chain have been corrupted, the memory to free is being put into the context it was taken from - global or in-block, etc.) Intended for calls from C. No meaningful return code. Umeminit Memory management initialization routine called from entry vector as Uentry walks it. Takes the Umembot and Umemtop global variable values, splits available memory in half, and places dynamic allocation heap in top half, and runtime stack in bottom half. Intended for call from entry vector only. CALLOC ------- CALLOC CLEARERR ------- CLEARERR CSEEK ------- CSEEK CTELL ------- CTELLC ------- CTELL DTOI ------- DTOI EXIT ------- ABORT ------- EXABRT ------- EXIT exabrt() when called from a user exit trap, causes a clean abort of the exit (i.e. the program continues from the point following its call to exit()). Side effects of aborting various exits are the responsibility of the programmer, since most code is **NOT** written expecting a return from exit(). Be sure you know what you are doing when using this facility. Likely DISASTROUS if called from any but an exit vector based routine, since assumptions about the stack are made. Intended for calls from C or assembler exit vector routines. No meaningful return code. abort(code) char code; /* alias for exit() */ exit(code) char code; /* alias for abort() */ stores value of code in global Uexcode, then proceeds to walk the exit vector, emulating calls to its routines. Intended for calls from C. Not normally returned from, except by exabrt() in user exit trap. FCLOSE ------- FCLOSE FEOF ------- FEOF FERROR ------- FERROR FFLUSH ------- FFLUSH FGETC ------- FGETC ------- GETC FOPEN ------- FOPEN FREE ------- CFREE ------- FREE GETARG ------- GETARG ISATTY ------- ISATTY ISCONS ------- INCONS ISFCNS ------- ISALNUM ------- ISALPHA ------- ISASCII ------- ISCNTRL ------- ISDIGIT ------- ISGRAPH ------- ISLOWER ------- ISPRINT ------- ISPUNCT ------- ISSPACE ------- ISUPPER ------- ISXDIGIT ITOA ------- ITOA ITOAB ------- ITOAB ITOD ------- ITOD ITOO ------- ITOO ITOU ------- ITOU ITOX ------- ITOX CMATCH ------- CMATCH cmatch(s,ch,from) find occurrence of a character in a string starting at offset "from". LEFT ------- LEFT LEXCMP ------- LEXCMP ------- LEXORDER ------- ULEX MALLOC ------- MALLOC OTOI ------- OTOI REVERSE ------- REVERSE SIGN ------- SIGN STRCAT ------- STRCAT STRCHR ------- STRCHR STRCMP ------- STRCMP STRCPY ------- STRCPY STRLEN ------- STRLEN STRNCAT ------- STRNCAT STRNCMP ------- STRNCMP STRNCPY ------- STRNCPY STRRCHR ------- STRRCHR TOASCII ------- TOASCII TOLOWER ------- TOLOWER TOUPPER ------- TOUPPER UNGETC ------- UNGETC UNLINK ------- DELETE ------- UNLINK UTOI ------- UTOI XTOI ------- XTOI CALL ------- CCAND ------- CCARGC ------- CCASL ------- CCASR ------- CCCMP ------- CCCOM ------- CCDCAL ------- CCDDGC ------- CCDDGI ------- CCDECC ------- CCDECI ------- CCDIV ------- CCDSGC ------- CCDSGI ------- CCEQ ------- CCGCHAR ------- CCGE ------- CCGINT ------- CCGT ------- CCINCC ------- CCINCI ------- CCLE ------- CCLNEG ------- CCLT ------- CCMULT ------- CCNEG ------- CCNE ------- CCOR ------- CCPCHAR ------- CCPDPC ------- CCPDPI ------- CCPINT ------- CCSUB ------- CCSWITCH ------- CCSXT ------- CCUCMP ------- CCUGE ------- CCUGT ------- CCULE ------- CCULT ------- CCXOR ------- CDPDPC ------- CDPDPI Description of this module as a whole: This contains the internal arithmetic and logical routines - the stuff that makes "if" expressions and operators operate. Called by name by compiler generated in-line code. UPGMEND ------- UPGMEND * not a routine, but important enough to include * SCZ CLIB version number follows pgm end eyecatcher * db '>>>>SCZCLB0.1',0 * this is also default stack bottom