These are supplemental functions, currently covering: 0) others (anything else) 1) environment handling (env_*.c) 2) MCB handling (mcb_*.c) 3) far memory access for Micro-C (f*.c) 4) additional functions for longmath Micro-C only (long*.c) 5) getopt() functionality (getopt*.c) 6) filename functions (dfn*.c) 7) dynamic string functions (dstr*.c, dmem*.c) There are some functions for Micro-C only. They will be compiled with Borland C, too, but they result in an empty OBJ file (only containing the module header and trailer and the debug info). No program size or symbols are located in them. Newly added is the support for Pacific C (Hi tech C) compiler v7.51 (PAC). C sources not dedicated for PAC are simply ignored. Overview about what to compile with what compiler: *.C all compiler, some files will produce an empty output *.ASM Micro-C only *.AS Pacific C only Note: These patterns might change in the future! When making the library via DMAKE, LIB will possibly warn for not found OBJ files. This sucks but it seems that the Make rule is incorrectly informed that all prerequisites are out-of-date. Notes: 0.1) ctrlbrk.c: ctrlbrk(fct) cb_catch.asm: _cbreak_catcher (companion for ctrlbrk()) Micro-C only! pac_cbc?.as: _cbreak_catcher_?? (companion for ctrlbrk()) PAC only! Installs a hook on the DOS called ^Break interrupt to call the function fct. If fct() returns with a zero value, the current program will be terminated by DOS. longjmp() should be possible within fct(). 0.2) poked.c: poked(seg,ofs,dword) pokedd.c: pokedd(seg,ofs,hi,lo) peekd.c: peekd(seg,ofs,&dword) peekdd.c: peekdd(seg,ofs,&hi,&lo) Peeking/poking double word values from/into memory, *d() uses the dword structure; *dd() two word values. The peek*() functions return 0, if the peek()'ed value is zero. The pointers in the *dd() function maybe NULL; in this case the particular value is not copied. The peekdd() function return in Bit 0, if the *hi value is non-zero; and in Bit 1, if the *lo value is non-zero. 0.3) mem*.c, st*.c: String handling functions for Micro-C/Pacific C: stpcat.c: stpcat(): Concats two strings and return the end address strtol.c: strtol(): Transforms a number in ASCII notation into its binary interpretation. Various radixes and C-style numbers are supported. memicmp.c: memicmp(): as stricmp(), but for a memory block 0.4) dosalloc.c: DOSalloc(): Allocate a chunk of memory via the DOS API and automatically link in UMB chain and set the allocation strategy. Or return largest available block of memory. dosfree.c: DOSfree(): Free an allocated chunk. dossize.c: DOSresize(): Resize an allocacted chunk. byte2par.c: BLK_byte2para(): Calculate the number of paragraphes needed to hold an amount of bytes (both (unsigned) range). 0.5) addu.c: addu(): Performs a += operation and returns, if an overflow occured. 0.6) setdisk.c/getdisk.c: setdisk()/getdisk() for PAC. 1.1) The implementation does not make use of far pointers, rather it addresses via the segment:offset pair. To access the far memory the peek*() functions or the _fmem*()/_fstr*() functions are used. 1.2) There is no getenv() function. This is because this function differs between Micro-C and other compilers, but is used internally in the C libraries. Use the cpyenv() function instead. 1.3) The functionality covers both the environment strings and the additionial string area at the end. 1.4) All functions assume that the string area is initialized. This is true for DOS 3.0+ and all environments initialized by functions of this library. 1.5) The size of the environment can range from 1..65535 bytes. If it is larger than that, the portion above 64KB is lost. If this portion is already in use, the behaviour of the functions, except env_check() and env_delete(), are undefinied. Note: To my knowledge MS-DOS's accessable largest environment is 32KB. 1.6) If "0" is specified as the segment address, most of the functions replace it by the current used environment. The env_replace() function will also call the env_setGlbSeg() function in this case. 1.7) No shell I know supports the string table in their environment segment. Because all functions assumes that the string table is present, the env_nullStrings() function will initialize an empty string table. 2.1) All functions to identify owners and shells of memory blocks. 2.2) Most of the functions uses the MCB number rather the "normal" memory handle used by DOS API functions. The macros MCB2SEG() and SEG2MCB() transform between both numbers. 3.1) The far memory implementation bases on the _fmem*()/_fstr*() functions of Borland C. Those functions require a far pointer at various places, which is created by the MK_FP() macro. The Micro-C implementation simply leaves both values in the parameter list, thus, passing two arguments to the _f*() functions. This allows a quite useful protability between MC and other compilers, but does not handle the question of far pointer variables themselves. 3.2) The amount of implemented functions is limited to the currently used functions. ;-) 4.1) All provided longmath additions assume that the numbers are dwords! 4.2) The *i()/*u() functions provide the normal *() functionality, but the second operand, the one which is not the result, is an (int) or (unsigned int) value. 5) All functions to scan the command line arguments for options. Due to licensing conflicts these files had been removed. Please use the implementation contain in SUPPL v2.7 pre, which is POSIX compatible. 6.0) The filename functions base upon dynamic memory. This allows to forget about the "maximal" length of some components, and thus, it can handle any-sized filenames, including "long" filenames of newer filesystems. 6.0.1) DFN_FILENAME_BUFFER_LENGTH: constant that defines how large the internal buffers are, that shall hold a fully-qualified filename. Currently it's 512 bytes. (Twice as much as one path component in Win95 can have.) This value is only used, if a buffer must be created, that will receive a path from the operating system's API. 6.0.2) If the macro SUPPORT_UNC_PATH is defined before #include'ing the "dfn.h" header file, the dfn*() functions are mapped to the ones, which will handle UNC path specifications. You should not intermix calls to functions supporting and not supporting UNC paths. The functions assume that the path is an UNC path, if it starts with two backslashes; the UNC drive itself will then consume all characters up to the second backslash, e.g.: \\server\volume\path\filename.ext \\server\volume both return "\\\\server\\volume" as UNC drive spec. Note: To my knowledge most UNC paths are formed like that; but, of course, there is an exception; in MS Windows for Workgroups Network the second portion, called "volume" above, is missing. 6.1) dfnsplit.c: dnfsplit(): split a filename into its components. The filename is not (except flipping '/' -> '\\' & squeezing multiple '\\') altered in any way. 6.2) dfnmerge.c: dnfmerge(): merge components into a filename. It is possible to use "ill-formed" arguments, such as: dnfmerge(NULL, "a", "path\\name.ext", NULL, NULL); --> "a:path\\name.ext" 6.3) dfnsquee.c: dfnsqueeze(): upcase the filename, flips '/' -> '\\', squeezes '\\\\' -> '\\', '\\.\\' -> '\\', '\\.\0' -> '\\'. 6.4) dfnpath.c: dfnpath(): return the fully-qualifed path of the current working directory of the specified drive. 6.5) dfnexpan.c: dfnexpand(): expand a filename to a fully-qualified one. Expanding is made according a given fully-qualified path or the current working directory of the particular drive. 6.6) dfntruen.c: dfntruename(): return the physical access path of the given file. The file need not exist. The returned path is dedicated for comparing, if two logical access paths point to the same file in reality. The physical access path need not to be accessable through the DOS API calls. 6.7) dfnsearc.c: dfnsearch(): search a file through a PATH and with varying extensions. 6.8) dnfmatch.c: dfnmatch(): match a filename against a (DOS-wildcard) pattern 6.8) dnfmatc2.c: dfnmatch2(): match a filename against a (Win32-wildcard) pattern 7.0) The dynamic string functions assume that the strings are hold in the heap. All functions start with "Str" and the next component also starts with a capital letter. 7.0.1) If an argument of such function receives a dynamic string as a result, the function is a macro that creates a pointer from this argument, e.g.: #define StrRepl(dest,src) StrRepl_(&(dest),(src)) char *StrRepl_(char **dest, char *src); The naming convention is the same with all functions. On the other hand, the pointer 'dest' is never checked for NULL and the pointer '*dest' must be pre-initialized, because the prior is free()'ed. 7.1) dstrchar.c: StrChar(): create a new string containing of the single letter 7.2) dstrconc.c: StrConcat(): create a new string containing the concatenation of all arguments. 7.3) dstrrepl.c: StrRepl(): assigns a string to a dynamic string variable. The string is not duplicated. dstrrepl.c: StrFree(): assigns NULL. 7.4) dstrstri.c: StrStrip(): strip any number of the given character from the end of the string. 7.5) dstrtrim.c: StrTrim(): reallocate a dynamic string to the lenght: (strlen(string) + 1) 7.6) toUpperx.c: toUpper(): upcases a character using the DOS NLS API. toUpperx.c: toFUpper(): upcases a character using the DOS NLS API according the upcase table for filenames. toUpperx.c: rereadUpcaseTable(): causes to re-read the internally stored pointers to the upcase tables for normal characters and for filenames. dstrcmp.c: StriCmp(): compare two strings case-insensitively using toUpper() dstrcmpf.c: _fStriCmp(): compare two far strings case-insensitively using toUpper() dmemcmp.c: MemiCmp(): compare two memory areas case-insensitively using toUpper() dmemcmpf.c: _fMemCmp(): compare two far memory areas case-insensitively using toUpper() dmemcmp2.c: MemFCmp(): compare two memory areas case-insensitively using toFUpper() dmemcmp3.c: _fMemFCmp(): compare two far memory areas case-insensitively using toFUpper() dstrupr.c: StrUpr(): Upcase the string using the toUpper() function. dmemupr.c: MemUpr(): Upcase the memory area using the toUpper() function. dstruprf.c: _fStrUpr(): Upcase the string using the toUpper() function. dmemuprf.c: _fMemUpr(): Upcase the memory area using the toUpper() function. 7.7) dstrdup.c: StrDup(): Duplicate string. 7.8) dstrcpy.c: StrCpy(): Copy (duplicate) a string into a variable. 7.9) dstrcat.c: StrCat(): Append a string to a string. 7.10) dstrappe.c: StrAppend(): Append a string including delimiting and quoting the appended string. 7.11) dstrappc.c: StrAppChr(): Append a single character to a string. 7.12) dstrtoke.c: StrTokenize(): analogeous of strtok(), but non-destructive dstrtoke.c: StrSaveTokens(): makes StrTokenize() re-entrant 7.13) dstrleft.c: StrLeft(): Return the left portion of a string dstrrigh.c: StrRight(): Return the right portion of a string dstrmid.c: StrMiddle(): Return a specific portion out of a string dstrtail.c: StrTail(): Return the last portion of a string 7.14) dstrbeg.c: StrBeg(): Compare if one string begins with another 7.15) isodigit.c: isodigit(): Check for an octal digit toxdigit.c: toxdigit(): Transform an hexa-decimal digit into an integer number 7.16) dstrcstr.c: StrCString(): Interprete C-style character string