Power-Programmierung

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

/ Power-Programmierung / CD2.mdf / c / library / dos / screen / mflms101 / mfl_func.man < prev next >

Wrap

Text File | 1989-11-23 | 313.8 KB | 16,963 lines

TITLE_PG.FM - Thu 23 Nov 89 00:19 - Page 1: The MicroFirm Function Library for Microsoft C & Quick C ver 1.01 Copyright 1988-89 by Robert B. Stout dba MicroFirm portions Copyright 1986-87 by Stephen E. Margison All rights reserved --------------------------------------- LIBRARY FUNCTIONS IN ALPHABETICAL ORDER --------------------------------------- AABORT.FNC - Thu 23 Nov 89 00:19 - Page 2: NAME aabort -- terminate a program PROTOTYPED IN: mflsys.h SYNOPSIS void aabort(code); int code; exit error code DESCRIPTION The program is aborted (using the common_exit() function) after sending the BELL character to stderr. By using the common_exit() routine, any common exit function which has been installed will be called. EXAMPLE aabort(0); ANSISYS.FNC - Thu 23 Nov 89 00:19 - Page 3: NAME ansisys -- detects ANSI.SYS PROTOTYPED IN: mflsys.h SYNOPSIS r = v_init(); LOGICAL r; TRUE if ANSI.SYS is loaded, FALSE if ANSI.SYS is not loaded, ERROR if function failed DESCRIPTION The ansisys() function detects the presence of ANSI.SYS or compatible device driver (e.g. ZANSI, FANSI, etc.) Note that ansisys() requires a PC to be closely compatible with IBM at the BIOS interrupt level. EXAMPLE LOGICAL aflag; if (ERROR == (aflag = ansisys())) puts("can't tell if ANSI.SYS is loaded"); else printf("ANSI.SYS is%s loaded\n", aflag ? "" : "n't"); SEE ALSO: make_ansi() ARGVAL.FNC - Thu 23 Nov 89 00:19 - Page 4: NAME argval -- convert an ASCII numerical string from an argument PROTORYPED IN: mflstrng.h SYNOPSIS i = argval(string, dest, i); int i; index into the current argument string which is returned incremented to the first character after the numerical string char *string; the string containing the numerical value int dest; destination for resultant integer value DESCRIPTION This function is primarily intended to parse command line arguments containing numerical values into an integer. The function will abort the program if the index points to a non-numeric digit upon entry with an error message and the option character which preceeds the index pointer. Numeric values cannot exceed four characters without causing potential damage to the program by overrunning the character storage area. EXAMPLE assume argv[1] = "-M30C" int i, value; i = 2 /* i is incremented to '3' by other code */ i = argval(&argv[1], value, i); after execution, i = 4 (pointing to 'C') value = 30 argv[1] is unchanged ATR2ANSI.FNC - Thu 23 Nov 89 00:19 - Page 5: NAME make_ansi -- translate video attributes to ANSI strings PROTOTYPED IN: mflconio.h SYNOPSIS astring = make_ansi(vattr); char *astring; the returned ANSI string int vattr; video attribute DESCRIPTION Given a standard video attribute byte, make_ansi() tanslates it into an ANSI control string. EXAMPLE char *astring; astring = make_ansi(YELLOW+(BLUE<<4)); SEE ALSO: ansisys() BADEXT.FNC - Thu 23 Nov 89 00:19 - Page 6: NAME badext -- report invalid filename extension and exit PROTOTYPED IN: mflfiles.h SYNOPSIS void badext(ext); char *ext; DESCRIPTION This function may be used when an invalid filename extension must cause the termination of a program. It is called with the offending extension as the argument string. An error message is sent to stderr, and the program terminates via the aabort() function of this library. SEE ALSO: exttyp() BITCLR.FNC - Thu 23 Nov 89 00:19 - Page 7: NAME BitClr -- clear n'th bit DEFINED IN: mfldefs.h SYNOPSIS BitClr(data,posn); void data; may be char, int, or long int posn; bit position to reset to 0; 0 = LSB DESCRIPTION The BitClr() function resets a particular bit to zero for a char, int or long data variable. EXAMPLE int flag; int mask=0xf0; /* mask (binary) = 11110000 */ mask = BitClr(mask,14); /* mask (binary) = 10110000 */ SEE ALSO: BitSet(), BitTst() BITSET.FNC - Thu 23 Nov 89 00:19 - Page 8: NAME BitSet -- set n'th bit DEFINED IN: mfldefs.h SYNOPSIS BitSet(data,posn); void data; may be char, int, or long int posn; bit position to set to 1; 0 = LSB DESCRIPTION The bitset() function sets a particular bit to 1 for a char, int or long variable. EXAMPLE int flag; int mask=0xf0; /* mask (binary) = 11110000 */ mask = BitSet(mask,1); /* mask (binary) = 10110010 */ SEE ALSO: BitClr(), BitTst() BITTST.FNC - Thu 23 Nov 89 00:19 - Page 9: NAME BitTst -- test n'th bit DEFINED IN: mfldefs.h SYNOPSIS BitTst(data,posn); void data; may be char, int, or long int posn; bit position to return; 0 = LSB DESCRIPTION The BitTst() function returns the bit position of a particular bit from a char, int or long variable. EXAMPLE int flag; flag = BitTst(mask,4); /* flag = TRUE */ SEE ALSO: BitClr(), BitSet() BLPR.FNC - Thu 23 Nov 89 00:19 - Page 10: NAME blpr -- write a character to LPT? through BIOS 17H PROTOTYPED IN: mflsys.h SYNOPSIS r = blpr(chr, num); int r; returns status in low 8 bits char chr; character to write int num; printer number 0-2 DESCRIPTION The blpr() function writes a character to LPT?. This assembly language routine provides very low-level access to the LPT1 - LPT3 drivers in the ROM-BIOS. Because of this dependency upon the ROM-BIOS Interrupt 17H, this function may not work on all compatibles. The normal DOS channel PRN: is bypassed, as is any re-assignment of LPT?. Normally, this routine is not used directly; rather, it is accessed through the "pr" series subroutine calls. Status bits are returned as follows: (meaning is with bit set) bit 0 = time out bit 1,2 are unused and should be ignored bit 3 = I/O error bit 4 = Printer Selected bit 5 = Out of Paper bit 6 = Acknowledged bit 7 = Not Busy EXAMPLE int i; i = blprstat(0); /* LPT1: is 0 */ if(!(i & 0x80)) puts("Printer is busy"); else blpr('A', 0); SEE ALSO: blprstat BLPRSTAT.FNC - Thu 23 Nov 89 00:19 - Page 11: NAME blprstat -- get LPT? status through BIOS 17H PROTOTYPED IN: mflsys.h SYNOPSIS r = blprstat(num); int r; returns status in low 8 bits int num; printer number 0-2 DESCRIPTION The blprstat() function obtains printer status. This function provides very low-level access to the LPT1 - LPT3 drivers in the ROM-BIOS. Because of this dependency upon the ROM-BIOS Interrupt 17H, this function may not work on all compatibles. The normal DOS channel PRN: is bypassed, as is any re-assignment of LPT?. Normally, this function are not used directly; rather, it is accessed through the "pr" series subroutine calls. Status bits are returned as follows: (meaning is with bit set) bit 0 = time out bit 1,2 are unused and should be ignored bit 3 = I/O error bit 4 = Printer Selected bit 5 = Out of Paper bit 6 = Acknowledged bit 7 = Not Busy EXAMPLE int i; i = blprstat(0); /* LPT1: is 0 */ if(!(i & 0x80)) puts("Printer is busy"); else blpr('A', 0); SEE ALSO: blpr() BPUTC.FNC - Thu 23 Nov 89 00:19 - Page 12: NAME Bputc -- write a character using BIOS only DEFINED IN: mfldefs.h SYNOPSIS Bputc(character); char character; character to write DESCRIPTION Since DOS is not re-entrant, you cannot (in general) call DOS functions from within interrupt handlers, including Ctrl-Break and critical error handlers as supported by ctlbrk() or criterr(). This function works identically to fputc(stderr) except that it writes directly to the screen via BIOS, bypassing all DOS calls. The only caution is that writing a '\n' using Bputc only causes a line feed. To achieve the normal (for C) newline function, you must either explicitly write an additional '\r' or simply use Bputs("\n") instead. EXAMPLE Bputc('\a'); SEE ALSO: Bputs(), ctlbrk(), criterr() BPUTS.FNC - Thu 23 Nov 89 00:19 - Page 13: NAME Bputs -- write a string using BIOS only PROTOTYPED IN: mflconio.h SYNOPSIS Bputs(string); char *string; string to write DESCRIPTION Since DOS is not re-entrant, you cannot (in general) call DOS functions from within interrupt handlers, including Ctrl-Break and critical error handlers as supported by ctlbrk() or criterr(). This functions works identically to fputs(stderr) except that it writes directly to the screen via BIOS, bypassing all DOS calls. Note that newline characters are properly translated into CR-LF pairs. EXAMPLE Bputs("Something's wrong!\n"); SEE ALSO: Bputc CANT.FNC - Thu 23 Nov 89 00:19 - Page 14: NAME cant -- report inability to open a file and exit PROTOTYPED IN: mflfiles.h SYNOPSIS void cant(name); char *name; filename to display DESCRIPTION This function is used to report a failure to open a file of "name", and then abort the program through the aabort() function of this library. EXAMPLE cant("foo.bar"); cant(argv[1]); CENTER.FNC - Thu 23 Nov 89 00:19 - Page 15: NAME center -- center a string PROTOTYPED IN: mflstrng.h SYNOPSIS r = center(string, size); int r; starting column for centering char *string; string to center int size; width of field for centering DESCRIPTION This function returns the starting column to print a string for the string to be centered in a field of "size" characters. For the screen, the width would usually be 80, and for printers, either 80 or 132. The string MUST NOT BE longer than the size specified, since there is no error cheking for this condition and an unusable result will be returned. EXAMPLE char title[] = "Title of Program"; main() { int i; i = center(title, 80); d_say(2, i, title); /* display title centered in row 2 */ } CHDRV.FNC - Thu 23 Nov 89 00:19 - Page 16: NAME chdrv -- change disk drives PROTOTYPED IN: mflfiles.h SYNOPSIS r = chdrv(drive); int r; returns ERROR if drive is invalid char drive; drive ('A' - 'Z') to check DESCRIPTION Chdrv() as an anlog of the chdir() function which changes drives rather than directories. It is not necesary, when using chdrv(), to validate the target drive using drvalid() since this is done automatically by chdrv(). EXAMPLE char drive; if ('C' != drive) { if (!chdrv('C')) puts("changed to drive C:"); else puts("\aunable to change drives"); } SEE ALSO: getdrv(), drvalid() CHKCTS.FNC - Thu 23 Nov 89 00:19 - Page 17: NAME chkcts -- check state of clear to send flag PROTOTYPED IN: mflsys.h SYNOPSIS r = chkcts(port); int r; TRUE or FALSE, depending upon state int port; 0, 1, 2, or 3 (for COM1-COM4) DESCRIPTION This function is part of a set of assembly language functions which provide direct access to the serial communications chips for the fastest access possible. Calling chkcts() checks the status of the clear to send and returns its state as TRUE (on) or FALSE (off). The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in <mflsys.h>. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ if(chkdcd(sport)) puts("Ok to send"); else puts("Don't send data now"); SEE ALSO: chkdcd(), chkdsr(), chkring() CHKDCD.FNC - Thu 23 Nov 89 00:19 - Page 18: NAME chkdcd -- check state of carrier detect flag PROTOTYPED IN: mflsys.h SYNOPSIS r = chkdcd(port); int r; TRUE or FALSE, depending upon state int port; 0, 1, 2, or 3 (for COM1-COM4) DESCRIPTION This function is part of a set of assembly language functions which provide direct access to the serial communications chips for the fastest access possible. Calling chkdcd() checks the status of the carrier detect flag and returns its state as TRUE (on) or FALSE (off). The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in <mflsys.h>. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ if(chkdcd(sport)) puts("We have a carrier detected"); else puts("The modem is apparently idle"); SEE ALSO: chkdsr(), chkcts(), chkring() CHKDSR.FNC - Thu 23 Nov 89 00:19 - Page 19: NAME chkdsr -- check state of data set ready flag PROTOTYPED IN: mflsys.h SYNOPSIS r = chkdsr(port); int r; TRUE or FALSE, depending upon state int port; 0, 1, 2, or 3 (for COM1-COM4) DESCRIPTION This function is part of a set of assembly language functions which provide direct access to the serial communications chips for the fastest access possible. Calling chkdsr() checks the status of the data set ready flag and returns its state as TRUE (on) or FALSE (off). The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in <mflsys.h>. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ if(chkdsr(sport)) puts("DSR flag is set"); else puts("DSR flag is not set"); SEE ALSO: chkdcd(), chkcts(), chkring() CHKRING.FNC - Thu 23 Nov 89 00:19 - Page 20: NAME chkring -- check state of ring indicator flag PROTOTYPED IN: mflsys.h SYNOPSIS r = chkring(port); int r; TRUE or FALSE, depending upon state int port; 0, 1, 2, or 3 (for COM1-COM4) DESCRIPTION This function is part of a set of assembly language functions which provide direct access to the serial communications chips for the fastest access possible. Calling chkring() checks the status of the ring indicator flag and returns its state as TRUE (on) or FALSE (off). The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in <mflsys.h>. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ if(chkring(sport)) puts("Ring indicator flag is set"); else puts("Ring indicator flag is not set"); SEE ALSO: chkdcd(), chkdsr(), chkcts() CLR_GAME.FNC - Thu 23 Nov 89 00:19 - Page 21: NAME clr_game() --- clear pending input from game port PROTOTYPED IN: mflsys.h SYNOPSIS (void)clear_game(); DESCRIPTION Calling clear_game() clears any pending input and forces the debouncer to assume a new input sequence. EXAMPLE main() { unsigned char i; init_game(FALSE); /* allow only single switch inputs */ for ever() { debounce(); /* call this regularly */ i = get_press(); if(i is 0) continue; printf("switch value is %x\n", i); } } SEE ALSO: init_game(), getpress(), debounce() CLRCAPS.FNC - Thu 23 Nov 89 00:19 - Page 22: NAME clrcaps() -- sets Caps lock to OFF PROTOTYPED IN: mflconio.h SYNOPSIS clrcaps(); DESCRIPTION This function forces the caps lock status flag to OFF. EXAMPLE setcaps(); if(kbstate(2)) puts("Caps lock is now set"); else puts("Caps lock is NOT set"); clrcaps(); puts("Caps lock should now be off"); SEE ALSO: _kbstate(), kbstatus(), setcaps(), clrcaps(), setnumlock(), clrnumlock() CLRFIELD.FNC - Thu 23 Nov 89 00:19 - Page 23: NAME clrfield -- clear a screen field through BIOS PROTOTYPED IN: mflconio.h SYNOPSIS void clrfield(row, col, size, page); int row, col; starting point int size; number of columns to clear ( <= 80) int page; video page number (for non-CGA, specify 0) DESCRIPTION This function handles the problem of clearing a section of a line on the screen without clearing to the end of the line. If the size parameter is larger than 80, it is forced to 80. EXAMPLE clrfield(10, 20, 15, 0); /* clear 15 columns on page 0 starting at row 10, column 20 */ SEE ALSO: disp_clrfield CLRNMLOC.FNC - Thu 23 Nov 89 00:19 - Page 24: NAME clrnmloc() --- turns numlock off PROTOTYPED IN: mflconio.h SYNOPSIS clrnumlock(); DESCRIPTION This function forces the numlok status flag to OFF. EXAMPLE setnumlok(); if(kbstate(2)) puts("Num lock is now set"); else puts("Num lock is NOT set"); clrnumlock(); puts("Num lock should now be off"); SEE ALSO: _kbstate(), kbstatus(), setcaps(), clrcaps(), setnumlock(), clrnumlock() CLS.FNC - Thu 23 Nov 89 00:19 - Page 25: NAME cls -- clear screen and home cursor PROTOTYPED IN: mflconio.h SYNOPSIS void cls(); DESCRIPTION This function clears the screen on page 0 and places the cursor in the upper left-hand corner. It is simply an invocation of two other functions: d_cls(); d_pos(0, 0, 0); EXAMPLE cls(); SEE ALSO: d_cls() CLSDIR.FNC - Thu 23 Nov 89 00:19 - Page 26: NAME closedir -- close a directory PROTOTYPED IN: mflfiles.h SYNOPSIS void closedir(d1); DOS_DIR *d1; directory file pointer DESCRIPTION The closedir() function closes the open directory whose file pointer is passed, just as fclose() closes normal DOS files. EXAMPLE char *name[] = "C:\looney\bin"; DOS_DIR *dirp; struct FIND *ffblk; if(dirp=opendir(name)) { printf("%s contains %d entries\n", name, dirp->dd_size); while (ffblk=readdir(dirp)) { printf("%3d - %s\n", dirp->dd_loc, ffblk->name); } closedir(dirp); } SEE ALSO: readdir(), opendir() CRC2CLR.FNC - Thu 23 Nov 89 00:19 - Page 27: NAME crc16_clr() --- clear crc value PROTOTYPED IN: mflmath.h SYNOPSIS r = crc16_clear(); unsigned r; 16-bit crc to clear DESCRIPTION This function is part of a group of functions used to do crc calculations. crc16_clear is used to clear the crc value. However, if speed is a concern, just zero the crc value since crc16_clear does nothing other than return a zero. EXAMPLE unsigned crc; crc = crc16_clear(); /* for each character processed: */ crc = crc16_update(crc, next_chr); /* finally, */ crc = crc16_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc16_update(), crc16_finish(), crc32_clear() crc32_update(), crc32_finish() CRC2FNSH.FNC - Thu 23 Nov 89 00:19 - Page 28: NAME crc16_finish() --- finish crc calculation PROTOTYPED IN: mflmath.h SYNOPSIS r = crc16_finish(crc); unsigned r; final 16-bit crc value unsigned crc; old 16-bit crc value DESCRIPTION This function is part of a group of functions used to do crc calculations. Calling crc16_finish() crc16_finish actually calls crc16_update twice with a value of 0 in order to flush the 16 bit calculation and return the final crc calculation. As supplied, the CCITT calculation polynomial is used. The source can be easily changed to CRC16 if desired. EXAMPLE unsigned crc; crc = crc16_clear(); /* for each character processed: */ crc = crc16_update(crc, next_chr); /* finally, */ crc = crc16_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc16_clear(), crc16_update(), crc32_clear(), crc32_update(), crc32_finish() CRC2UPDT.FNC - Thu 23 Nov 89 00:19 - Page 29: NAME crc16_update() --- update crc value PROTOTYPED IN: mflmath.h SYNOPSIS r = crc16_update(crc, chr); unsigned r; new 16-bit crc value unsigned crc; old 16-bit crc value char chr; datum DESCRIPTION This function is part of a group of functions used to do crc calculations. crc16_update is called once for each character to add to the crc. It receives the running crc and the character to be added. As supplied, the CCITT calculation polynomial is used. The source can be easily changed to CRC16 if desired. EXAMPLE unsigned crc; crc = crc16_clear(); /* for each character processed: */ crc = crc16_update(crc, next_chr); /* finally, */ crc = crc16_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc16_clear(), crc16_finish(), crc32_clear(), crc32_update(), crc32_finish() CRC4CLR.FNC - Thu 23 Nov 89 00:19 - Page 30: NAME crc32_clr() --- clear crc value PROTOTYPED IN: mflmath.h SYNOPSIS r = crc32_clear(); unsigned long r; 32-bit crc to clear DESCRIPTION This function is part of a group of functions used to do crc calculations. crc32_clear is used to clear the crc value. However, if speed is a concern, just zero the crc value since crc32_clear does nothing other than return a zero. EXAMPLE unsigned long crc; crc = crc32_clear(); /* for each character processed: */ crc = crc32_update(crc, next_chr); /* finally, */ crc = crc32_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc32_update(), crc32_finish(), crc16_clear(), crc16_update(), crc16_finish() CRC4FNSH.FNC - Thu 23 Nov 89 00:19 - Page 31: NAME crc32_finish() --- finish crc calculation PROTOTYPED IN: mflmath.h SYNOPSIS r = crc32_finish(crc); unsigned long r; final 32-bit crc value unsigned long crc; old 32-bit crc value DESCRIPTION This function is part of a group of functions used to do crc calculations. Calling crc32_finish() crc32_finish actually calls crc32_update twice with a value of 0 in order to flush the 16 bit calculation and return the final crc calculation. As supplied, the CCITT calculation polynomial is used. The source can be easily changed if desired. EXAMPLE unsigned long crc; crc = crc32_clear(); /* for each character processed: */ crc = crc32_update(crc, next_chr); /* finally, */ crc = crc32_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc32_clear(), crc32_update(), crc16_clear(), crc16_update(), crc16_finish() CRC4UPDT.FNC - Thu 23 Nov 89 00:19 - Page 32: NAME crc32_update() --- update crc value PROTOTYPED IN: mflmath.h SYNOPSIS r = crc32_update(crc, chr); unsigned long r; new 32-bit crc value unsigned long crc; old 32-bit crc value char chr; new datum DESCRIPTION This function is part of a group of functions used to do crc calculations. crc32_update is called once for each character to add to the crc. It receives the running crc and the character to be added. As supplied, the CCITT calculation polynomial is used. The source can be easily changed to CRC16 if desired. EXAMPLE unsigned long crc; crc = crc32_clear(); /* for each character processed: */ crc = crc32_update(crc, next_chr); /* finally, */ crc = crc32_finish; NOTE: These functions are from a public domain source, author unknown, They are not copyrighted. SEE ALSO: crc32_clear(), crc32_finish(), crc16_clear(), crc16_update(), crc16_finish() CRYPT.FNC - Thu 23 Nov 89 00:19 - Page 33: NAME crypt -- encrypt/decrypt data PROTOTYPED IN: mflsys.h SYNOPSIS crypt(buf); char *buf; datum to encrypt DESCRIPTION crypt implements a fully-reversible encryption algorithm which is simultaneously simple and fast, yet reasonably secure. The algorithm used is compatible with both the LYNX and CRYPT utilities of the MicroFirm Toolkit, ver 3.00 or later, and the crypt function of the CXL windowing library. EXAMPLE /* following externs declared in MFLSYS.H */ extern char *cryptext; /* the encryption key */ extern int crypt_ptr; extern int crypt_length; char *buf; /* data to encrypt */ crypt_ptr = 0; /* reset key pointer */ crypt_length = strlen(cryptext); while (*buf) { *buf = crypt(*buf); ++buf; } SEE ALSO: crypt_install(), cryptqual() CRYPTQUL.FNC - Thu 23 Nov 89 00:19 - Page 34: NAME cryptqual -- qualify an encryption key PROTOTYPED IN: mflsys.h SYNOPSIS r = cryptqual(key, keyl); LOGICAL r; SUCCESS if key qualifies, else ERROR char *key; prospective encryption key to test int keyl; number of unique characters required to qualify key (range 1-26) DESCCRIPTION Although the C-CODER algorithm implemented in crypt() and fcrypt() is capable of secure data encryption, it may be compromised by a poor choice of encryption key. While there's no way to protect from a poor judgement choice, the key may be qualified using the cryptqual() function to verify that it contains a sufficient number of unique characters. For example if 6 characters are required, "xxxxxx" would fail while "switch" would qualify. EXAMPLE char *key; /* "readers" fails - only 5 unique characters */ printf("%s %s\n", "readers", cryptqual("readers, 6) ? "failed" : "passed"); /* "spreaders" qualifies - 6 unique characters */ printf("%s %s\n", "spreaders", cryptqual("spreaders, 6) ? "failed" : "passed"); SEE ALSO: crypt(), crypt_install() CTLBRK.FNC - Thu 23 Nov 89 00:20 - Page 35: NAME ctlbrk -- control-break (^C) interrupt handler PROTOTYPED IN: mflsys.h SYNOPSIS r = ctlbrk(func); int *func; int r; return 0 to continue program, not zero to abort. DESCRIPTION This function is used to install a user-written interrupt handler for DOS int 23h, the Control-C handler. The default handler simply exits (ungracefully) the host program. Using ctlbrk(), a user-written handler may be substituted for the default. This may be desirable if it is absolutely necessary to prevent an untimely user-inspired exit, or if control-C is desired to perform some function within the program. The parameter passed is the address of the actual function. Passing a NULL parameter re-installs the handler which was in the interrupt table before this function altered the vector address. DOS re-installs the original handler upon any program exit, so it is unnecessary to uninstall this handler before actually exiting. EXAMPLE #include <stdio.h> #include <keys.h> handler() { Bputs("Control-C Received!!!\n"); /* couldn't use puts() which calls DOS */ return(0); /* continue program */ } main() { char ch; ctlbrk(&handler); ch = NULL; while(ch != ESC) /* loop until ESCAPE pressed */ ch = getche(); puts("Exiting program now. Have a nice day!"); } WARNING: Within the handler routine, keep the code simple and fast. DO NOT use printf() or its relatives as these will destroy the interrupt structure (for rather obscure reasons). CURSOR.FNC - Thu 23 Nov 89 00:20 - Page 36: NAME cursor_style -- alter the cursor style PROTOTYPED IN: mflconio.h SYNOPSIS void cursor_style(type, startscan, stopscan); int type; type of cursor as defined below int startscan; top scanline of cursor int stopscan; bottom scanline of cursor DESCRIPTION This function allows selection of several pre-defined cursor styles, or user-specified cursor size. If "type" is 0, then user must supply a starting scanline and stopping scanline value. If "type is 1-5, then these values may be set to anything to simply satisfy the argument count. Cursor scanlines are numbered from the top (0) to the bottom, which is 7 for CGA boards, and 13 for Monochrome Adapters. The Predefined values are: type == 1 Normal underline cursor for CGA type == 2 same, Mono Adapter type == 3 Block cursor for CGA type == 4 same, Mono Adapter type == 5 Cursor becomes invisible EXAMPLE /* for CGA video modes: */ cursor_style(4, 0, 0); /* set block cursor */ cursor_style(1, 0, 0); /* restore underline cursor */ cursor_style(0, 1, 7); /* set a very large block cursor */ D_CLS.FNC - Thu 23 Nov 89 00:20 - Page 37: NAME d_cls -- clear current screen PROTOTYPED IN: mflconio.h SYNOPSIS void d_cls(); DESCRIPTION This function clears the screen on the current page. EXAMPLE d_cls(); SEE ALSO: cls() D_POS.FNC - Thu 23 Nov 89 00:20 - Page 38: NAME d_pos -- position the cursor on a video page PROTOTYPED IN: mflconio.h SYNOPSIS void d_pos(r, c, p); int r; row number int c; column number int p; video page (must match current mode) DESCRIPTION This function positions the cursor on the specified video page. Row, column, and page values must match the current video mode. EXAMPLE d_pos(10, 15, 0); /* position cursor on row 10, column 15, video page 0 */ D_SAY.FNC - Thu 23 Nov 89 00:20 - Page 39: NAME d_say -- display a string at a specific position PROTOTYPED IN: mflconio.h SYNOPSIS void d_say(r, c, str); int r; row number int c; column number char *str; character string to display DESCRIPTION This function positions the cursor on the specified row and column on video page 0, and then writes the string. EXAMPLE d_say(10, 15, "Hello World!\n"); CAVEAT: The string is written to stdout. Therefore, the results will not be as advertised if stdout has been redirected from the default video output. Video page selection is only available on CGA adapters. SEE ALSO: d_saypag D_SAYPAG.FNC - Thu 23 Nov 89 00:20 - Page 40: NAME d_saypag -- position cursor with page specification, the write PROTOTYPED IN: mflconio.h SYNOPSIS void d_saypag(r, c, str, p); int r; row number int c; column number char *str; character string to display int p; video page (must match current mode) DESCRIPTION This function positions the cursor on the specified row and column on video page 0, and then writes the string. The d_saypag function also selects the video page on which to place the cursor. EXAMPLE d_saypag(5, 20, "Goodby!", 1); CAVEAT: The string is written to stdout. Therefore, the results will not be as advertised if stdout has been redirected from the default video output. Video page selection is only available on CGA adapters. SEE ALSO: d_say() DAYNUM.FNC - Thu 23 Nov 89 00:20 - Page 41: NAME daynum -- find the number of a date within a year PROTOTYPED IN: mfltime.h SYNOPSIS value = daynum(month, day, year); int value; number 1-366 int month; month number 1-12 int day; date of the month 1-31 int year; year, starting at 1980 DESCRIPTION This function returns the day number, 1-366, for the given date. By itself, this is not very useful, but the function is used as an intermediate calculation in certain other date routines. Years below 1980 are ignored. The year value is used to determine status as leap year. EXAMPLE for July 2, 1986: int value; value = daynum(7, 2, 1986); SEE ALSO: julian_to_yrday() DEBOUNCE.FNC - Thu 23 Nov 89 00:20 - Page 42: NAME debounce() -- input debouncer PROTOTYPED IN: mflsys.h SYNOPSIS (void)debounce(); input debouncer DESCRIPTION This function is part of a series of functions used to read and debounce the four switch inputs on the joystick input port. The analog joystick inputs are not supported. debounce() must be called periodically in order to debounce and process the switch inputs. It is suggested that debounce() be called about 75 to 100 times per second. The structure "gamesw" contains information used by these routines. The number of times debounce must be invoked to return a valid input is contained in gamesw.seed, and may be altered as desired. Switch values are returned as an 8 bit value, with only the lowest 4 bits in use. A set bit indicates a closed switch. If multiple keystrokes are not allowed, then get_press() will return 0, 1, 2, 4, or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be returned. bit position pin number on connector 0 2 1 7 2 14 3 10 EXAMPLE main() { unsigned char i; init_game(FALSE); /* allow only single switch inputs */ for ever() { debounce(); /* call this regularly */ i = get_press(); if(i is 0) continue; printf("switch value is %x\n", i); } } SEE ALSO: init_game(), clear_game(), get_press() DELFILES.FNC - Thu 23 Nov 89 00:20 - Page 43: NAME del_files -- delete files using FCB functions PROTOTYPED IN: mflfiles.h SYNOPSIS r = del_files(dir,mask); int r; ERROR if directory could not be located, else SUCCESS char *dir; directory where files are located char *mask; filename mask DESCRIPTION Using standard C functions such as find first/next and unlink() to delete multiple files is dramatically slower than when COMMAND.COM does it. It turns out that the speed advantage is due to the use of the FCB delete call which can accept wildcards. The del_files() function works the same way as COMMAND.COM and can wipe out whole directories full of files in a flash. EXAMPLE char *path="C:\PATH\BRANCH", *mask="*.BAK"; if (ERROR == delfiles(path,mask)) printf("Couldn't find %s\n", path); else printf("Files matching %s in %s deleted\n", mask, path); SEE ALSO: unlink() DIRMASK.FNC - Thu 23 Nov 89 00:20 - Page 44: NAME dirmask -- vaidate directory entry w/ name and attribute masks PROTOTYPED IN: mflfiles.h SYNOPSIS r = dirmask(ffblk, y_mask, n_mask, y_atr, n_atr); int r; SUCCESS if entry validated, else ERROR struct FIND *ffblk; directory entry to validate char *y_mask; name inclusion mask - validate if this name matches the entry's - NULL matches all char *n_mask; name exclusion mask - validate if this name does not matches the entry's - NULL matches none unsigned y_atr; attribute inclusion mask - FA_ANY matches all unsigned n_atr; attribute exclusion mask - 0 matches none DESCRIPTION The dos_findfirst/next functions provide no convenient way to do exclusion searches or to validate file attributes. For example if you try looking for directories using findfirst and an attribute of FA_DIREC, you'll soon find that DOS returns all directories PLUS all normal files. The dirmask() function operates on a FIND structure to validate its name and attribute members. The first parameter is a file spec which must match for the directory entry to be validated. The second is a file spec which will prevent validation. The third parameter is an attribute mask which must match the entry's attributes for validation. The fourth is an attribute mask which will prevent validation. Specifying NULL for either of the name specs will cause the corresponding validation to be skipped. Specifying FA_ANY for the inclusion attribute will match all entries. Specifying 0 for the exclusion attribute will cause no entries to be rejected. DIRMASK.FNC - Thu 23 Nov 89 00:20 - Page 45: EXAMPLE DOS_DIR *dirp; struct FIND *ffblk; /* print all non-.OBJ files beginning with 'A'... ...with the archive bit set which aren't directories */ dirp = opendir(fname); do { if (NULL != (ffblk = readdir(dirp))) { if (SUCCESS == dirmask(ffblk, "A.*", "*.OBJ", FA_ARCH ,FA_DIREC); printf("%3d - %s\n", dirp->dd_loc, ffblk->name); } } while (ffblk); puts("EOF\n"); closedir(dirp); SEE ALSO: wildname(), opendir(), readdir() closedir(), rfind_1st(), rfind_nxt() DRVALID.FNC - Thu 23 Nov 89 00:20 - Page 46: NAME drvalid -- see if a drive is valid PROTOTYPED IN: mflfiles.h SYNOPSIS r = drvalid(drive); int r; returns TRUE if valid, else FALSE char drive; drive ('A' - 'Z') to check DESCRIPTION Drvalid() tests if a specified drive is valid. FALSE will be returned for non-existent drives or for a floppy drive with the door open or with an unformatted diskette. This function works by attempting to do an absolute disk read of sector zero and avoids the DOS critical error (ABORT, RETRY, etc.) handler. Note that the drive specification passed to drvalid() may be either upper or lower case. EXAMPLE char drive; if(drvalid('a')) puts("Drive valid!"); else puts("Drive not currently valid!"); SEE ALSO: getdrv, chdrv DSTR_I.FNC - Thu 23 Nov 89 00:20 - Page 47: NAME dstr_i -- make an ascii decimal string into an integer PROTOTYPED IN: mflstrng.h SYNOPSIS c = dstr_i(p, r); char *p; int *r; int c; DESCRIPTION Read a string of ascii decimal digits and create an integer from the result. String must begin with a digit, +, or -. Calculation proceeds to first non-ascii digit or NULL terminator. Count of actual digits read is returned, and integer is placed in specified destination. '-' sign as first character returns integer negated. EXAMPLE char string[] = "1357"; int result; int count; count = dstr_i(string, &result); /* count will equal 4 result will equal 1357 */ DV_ATTR.FNC - Thu 23 Nov 89 00:20 - Page 48: NAME dvid_attrib -- set direct video attribute (color) PROTOTYPED IN: mflconio.h SYNOPSIS dvid_attrib(attrib); int attrib; video attribute to set DESCRIPTION The dvid_attrib() function sets the video attribute used for subsequent memory writes. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_getattr() DV_BIOS.FNC - Thu 23 Nov 89 00:20 - Page 49: NAME dvid_bios() -- force use of bios routines PROTOTYPED IN: mflconio.h SYNOPSIS dvid_bios(void); DESCRIPTION The dvid_bios() function may be called to force use of ROM BIOS services if problems are encountered using memory access. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. DV_BOX.FNC - Thu 23 Nov 89 00:20 - Page 50: NAME dvid_box -- display a box on the screen PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_box(row, col, width, height, style); int row, col; position to display upper left corner int height, width; size of box int style; 0 = single line, 1 = double line, 2 = single line reverse video, 3 = double line reverse video DESCRIPTION This function uses the features of the MicroFirm Function Library display package functions, and must therefore follow the rules laid down for their use. Specifically, disp_init() must be called prior to using this function, and the functions may fail of the target system is not a very close compatible since direct memory writing is being used. dvid_box places a single line or double line box on the screen with the upper left corner anchored at "row" and "column", with the size denoted by the "height" and "width" values. No error checking is done on any value. Invalid values may have unpredictable results. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_box(0, 0, 80, 24, 1); /* border the entire screen */ /* with double graphics line */ CAVEAT: if a color attribute has been set before this call, it will revert to black & white if the "reverse video" outlines are selected. The attribute is not changed for the normal video border selections. SEE ALSO: mkbox() DV_CATR.FNC - Thu 23 Nov 89 00:20 - Page 51: NAME dvid_char_atr -- dvid_char_at, returns cursor to start PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_char_atr(row, col, char); int row, col; position to display char *string; string to display char ch; character to display DESCRIPTION This function uses the features of the MicroFirm Function Library's display package functions, and therefore, must follow the rules laid down for their use. Specifically, dvid_init() must be called prior to using this function, and the function may fail if the target system is not a very close compatible since direct memory writing is being used. dvid_char_atr() read the current real cursor position and perform a dvid_move() after writing the specified data. Before using this call, be sure the display package cursor position and the screen position are equal by doing a dvid_flush() call. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_say(0, 0, "Hello"); /* write to upper left corner */ for(i = 0; i < 10; i++) { dvid_char_at(i, i+1, i | '0'); /* write a sequence */ } dvid_move(12, 40); /* move to center of screen */ dvid_flush(); /* physically update screen cursor */ dvid_sayr(20, 70, "Goodby"); /* write into lower corner */ dvid_putchr('!'); /* this char should be at 12, 40 */ SEE ALSO: dvid_say(), dvid_sayr(), dvid_char_at() DV_CHAT.FNC - Thu 23 Nov 89 00:20 - Page 52: NAME dvid_char_at -- display character at specified position PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_char_at(row, col, ch); int row, col; position to display char *string; string to display char ch; character to display DESCRIPTION This function uses the features of the MicroFirm Funtion Library's display package functions, and must therefore follow the rules laid down for their use. Specifically, dvid_init() must be called prior to using this function, and the function may fail if the target system is not a very close compatible since direct memory writing is being used. dvid_char_at() passes only a carriage return, linefeed, backspace, tab, and bell control code. All other control codes are ignored. Before using this call, be sure the display package cursor position and the screen position are equal by doing a dvid_flush() call. dvid_char_at() performs the dvid_flush() call before returning, thereby insuring cursor updating. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_say(0, 0, "Hello"); /* write to upper left corner */ for(i = 0; i < 10; i++) { dvid_char_at(i, i+1, i | '0'); /* write a sequence */ } dvid_move(12, 40); /* move to center of screen */ dvid_flush(); /* physically update screen cursor */ dvid_sayr(20, 70, "Goodby"); /* write into lower corner */ dvid_putchr('!'); /* this char should be at 12, 40 */ SEE ALSO: dvid_say(), dvid_sayr(), dvid_char_atr() DV_CHATR.FNC - Thu 23 Nov 89 00:20 - Page 53: NAME dvid_chgattrib -- alter attribute in an area PROTOTYPED IN: mflconio.h SYNOPSIS dvid_chgattrib(srow, scol, erow, ecol, attrib); int srow; starting row number int scol; starting column number int row; absolute row number int ecol; ending column number int attrib; video attribute DESCRIPTION The dvid_chgattrib() function may be used to alter the attributes on a region of the screen starting at row (srow) and column (scol), up to and including (erow) and (ecol), to the new (attribute). This provides a means of changing the color of a region of the screen from 1 character to the full screen without altering the character data in memory. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. DV_CLFLD.FNC - Thu 23 Nov 89 00:20 - Page 54: NAME dvid_clrfield -- clear a screen field PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_clrfield(row, col, size); int row, col; starting point int size; number of columns to clear ( <= 80) int page; video page number (for non-CGA, specify 0) DESCRIPTION This function handles the problem of clearing a section of a line on the screen without clearing to the end of the line. dvid_clrfield() will use the current screen attribute. The field is cleared to ASCII spaces. If the size parameter is larger than 80, it is forced to 80. EXAMPLE dvid_clrfield(10, 20, 15, 0); /* clear 15 columns on page 0 starting at row 10, column 20 */ SEE ALSO: dvid_cls() DV_CLS.FNC - Thu 23 Nov 89 00:20 - Page 55: NAME dvid_cls -- clear the display and home cursor PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_cls(); DESCRIPTION This function uses the features of the MicroFirm Funtion Library's display package functions, and must therefore follow the rules laid down for their use. Specifically, dvid_init() must be called prior to using this function, and the function may fail if the target system is not a very close compatible since direct memory writing is being used. dvid_cls() will clear the screen. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_say(0, 0, "Hello"); /* write to upper left corner */ for(i = 0; i < 10; i++) { dvid_char_at(i, i+1, i | '0'); /* write a sequence */ } dvid_move(12, 40); /* move to center of screen */ dvid_flush(); /* physically update screen cursor */ dvid_sayr(20, 70, "Goodby"); /* write into lower corner */ dvid_putchr('!'); /* this char should be at 12, 40 */ SEE ALSO: dvid_clrfield(), d_cls() DV_DONE.FNC - Thu 23 Nov 89 00:20 - Page 56: NAME dvid_done -- de-initialize the functions PROTOTYPED IN: mflconio.h SYNOPSIS dvid_done(void); DESCRIPTION The dvid_done() function is called before exiting a program to restore screen characteristics. It may also be used from within a program to restore all default values within the direct video package. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_init() DV_EEOL.FNC - Thu 23 Nov 89 00:20 - Page 57: NAME dvid_e2eol -- erase from cursor to end of line PROTOTYPED IN: mflconio.h SYNOPSIS dvid_e2eol(void); DESCRIPTION The dvid_e2eol() function is used to erase (to spaces) the screen from the current internal cursor position to the end of the line e2eol. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_e2eos() DV_EEOS.FNC - Thu 23 Nov 89 00:20 - Page 58: NAME dvid_e2eos -- erase cursor to end of screen PROTOTYPED IN: mflconio.h SYNOPSIS dvid_e2eos(void); DESCRIPTION The dvid_e2eos() function is used to erase (to spaces) the screen from the current internal cursor position to the end of the current video page. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_e2eol() DV_FLUSH.FNC - Thu 23 Nov 89 00:20 - Page 59: NAME dvid_flush -- update real cursor position PROTOTYPED IN: mflconio.h SYNOPSIS dvid_flush(void); DESCRIPTION The dvid_flush() function is called to force the onscreen cursor to the position defined by the "internal" cursor position. During video writes, an internal cursor position is maintained, but the onscreen cursor is NOT automatically updated to reflect the current writing position. This function resolves the discrepancy. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_move() DV_GTATR.FNC - Thu 23 Nov 89 00:20 - Page 60: NAME dvid_getattr -- fetch the current attribute PROTOTYPED IN: mflconio.h SYNOPSIS attrib = dvid_getattr(void); int attrib; video attribute DESCRIPTION The dvid_getattr() function is used to return the current attribute used for writing. It will return the value previously set with dvid_attrib(). The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_attrib() DV_GTMOD.FNC - Thu 23 Nov 89 00:20 - Page 61: NAME dvid_getmode -- gets the current translation mode PROTOTYPED IN: mflconio.h SYNOPSIS r = dvid_getmode(); int r; current translation mode (raw = TRUE) DESCRIPTION The dvid_getmode() function retrieves the current control character translation mode. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_raw() DV_INIT.FNC - Thu 23 Nov 89 00:20 - Page 62: NAME dvid_init -- initialize the direct video functions PROTOTYPED IN: mflconio.h SYNOPSIS dvid_init(void); DESCRIPTION The dvid_init() function MUST be called before any other dvid* functions are used. This function discovers the type of video card and mode in use and sets internal variables accordingly. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_done() DV_MOVE.FNC - Thu 23 Nov 89 00:20 - Page 63: NAME dvid_move -- set internal cursor position PROTOTYPED IN: mflconio.h SYNOPSIS dvid_move(row, col); int row; absolute row number int col; absolute column number DESCRIPTION The dvid_move() function sets the "internal" cursor to the specified (row) and (col) positions. Subsequent writes to the screen will begin at this position. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. DV_NTERD.FNC - Thu 23 Nov 89 00:20 - Page 64: NAME dvid_enterdata -- enter a string of data from keyboard PROTOTYPED IN: mflconio.h SYNOPSIS r = dvid_enterdata(dest, qty, row, col, mode); int r; returns TRUE or FALSE char *dest; destination for string int qty; maximum allowable chars + 1 int row, col; row and column of string start* int mode; mode for character checking DESCRIPTION This function provides a convenient method for entering character strings from the keyboard and verifying the character syntax. Line editing is supported to enhance user input. Entry is as follows: Carriage Return terminates input and returns TRUE. If no other data was entered, destination string is NULLed in the first position. CR is not placed into destination. ESCape terminates entry at once, NULLs destination, clears screen field, and returns FALSE. HOME clears field, and restarts entry without returning. BACKSPACE and Cursor Left will destructively backspace up to beginning of field. Only qty - 1 characters will be accepted. Any error sounds console BELL. Various modes allow for checking of syntax and mapping of characters: Mode 0: allow any printable character (ASCII 20H - 7FH) Mode 1: allow only alphabetics (A-Z, a-z) Mode 2: allow alphabetics and numerals only Mode 3: allow numerials only Mode 4: allow hexadecimal characters only (0-9, A-F, a-f) Modes 0, 1, and 2 will map lower case to upper case if decimal 128 (80H) is OR'd with the mode. DV_NTERD.FNC - Thu 23 Nov 89 00:20 - Page 65: EXAMPLE char string[31]; unsigned int num; d_pos(10, 20, 0); /* cursor to row 10, column 20 */ fputs("Enter an alphabetic string: ", stdout); if(!dvid_enterdata(string, 31, 10, 48, 1)) { fputs("\nESCape was pressed"); } else printf("\nString entered is %s\n", string); fputs("Enter hex value at current cursor position: ", stdout); if(!dvid_enterdata(string, 5, -1, 0, 4)) { fputs("\nESCape was pressed"); } else { num = atoi(string); printf("Number entered was %4x", num); } SEE ALSO: dvid_enterfn(), enterdata() DV_NTERF.FNC - Thu 23 Nov 89 00:20 - Page 66: NAME dvid_enterfn -- enter a filename from keyboard PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_enterfn(dest, qty, row, col, allow); char *dest; destination for string int qty; maximum allowable chars + 1 int row, col; row and column of string start* int allow; TRUE to allow entension entry DESCRIPTION This function provides a convenient method for entering a path and filename from the keyboard and verifying the character syntax. Line editing is supported to enhance user input. Entry is as follows: Carriage Return terminates input. If no other data was entered, destination string is NULLed in the first position. CR is not placed into destination. ESCape terminates entry at once, NULLs destination, and clears screen field. HOME clears field, and restarts entry without returning. BACKSPACE and Cursor Left will destructively backspace up to beginning of field. Only qty - 1 characters will be accepted. Any error sounds console BELL. If "allow" is TRUE, then a filename extension may be entered. Otherwise, no extension may be entered, since the period character will be disallowed. A drive may be specified; the colon is only allowed in the second character string position. EXAMPLE char string[31]; d_pos(10, 20, 0); /* cursor to row 10, column 20 */ fputs("Enter a filename: ", stdout); dvid_enterfn(string, 31, 10, 38, TRUE)); fputs("Enter filename at current cursor position: ", stdout); dvid_enterfn(string, 31, -1, 0, FALSE); SEE ALSO: dvid_enterdata(), enterfn() DV_PRNTF.FNC - Thu 23 Nov 89 00:20 - Page 67: NAME dvid_printf -- write a formatted string to screen PROTOTYPED IN: mflconio.h SYNOPSIS r = dvid_printf(str, ...); int r; number of characters written char *str; format string char ch; 8 bit character value DESCRIPTION The dvid_printf() function formats a string at the current internal cursor position. This may not be the visible cursor position, since the visible cursor is updated to the internal cursor only with the dvid_flush() function. Its syntax is identical to the familiar library printf() function. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_printfa(), dvid_putstr() DV_PRTFA.FNC - Thu 23 Nov 89 00:20 - Page 68: NAME dvid_printfa -- write formatted string to screen w/ attribute PROTOTYPED IN: mflconio.h SYNOPSIS r = dvid_printfa(attrib, str, ...); int r; number of characters written int attrib; video attribute (color) char *str; format string char ch; 8 bit character value DESCRIPTION The dvid_printfa() function formats a string at the current internal cursor position using the specified video attribute. This may not be the visible cursor position, since the visible cursor is updated to the internal cursor only with the dvid_flush() function. Its syntax is identical to the familiar library printf() function. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_printfa(), dvid_putsa() DV_PUTC.FNC - Thu 23 Nov 89 00:20 - Page 69: NAME dvid_putchr -- write a character to the screen PROTOTYPED IN: mflconio.h SYNOPSIS dvid_putchr(ch); char ch; 8 bit character value DESCRIPTION The dvid_putchr() function is the real workhorse of the direct video functions. It is this function which writes the specified (char) to the screen memory with the current attribute at the current internal row/col position. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_putstr(), dvid_putsa() DV_PUTS.FNC - Thu 23 Nov 89 00:20 - Page 70: NAME dvid_putstr -- write a string to screen PROTOTYPED IN: mflconio.h SYNOPSIS dvid_putstr(str); char *str; character string char ch; 8 bit character value DESCRIPTION The dvid_putstr() function places a string at the current internal cursor position. This may not be the visible cursor position, since the visible cursor is updated to the internal cursor only with the dvid_flush() function. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_putchr(), dvid_putsa() DV_PUTSA.FNC - Thu 23 Nov 89 00:20 - Page 71: NAME dvid_putsa -- display a string with attribute PROTOTYPED IN: mflconio.h SYNOPSIS dvid_putsa(string,vattr); char *string; string to display int vattr; video attribute to use DESCRIPTION The dvid_putsa function works exactly the same as fputs and requires the use of the display package (i.e. dvid_init must have previously been called). The specified string is displayed in the specified attribute. Any newline characters, embedded or trailing, will invoke a temporary switch back to the old attribute, thus attribute bleeding when scrolling. EXAMPLE dvid_putsa("This is\na test",YELLOW+(BLUE<<4),NORMAL); SEE ALSO: dvid_init() DV_RAW.FNC - Thu 23 Nov 89 00:20 - Page 72: NAME dvid_raw -- set display mode for control characters PROTOTYPED IN: mflconio.h SYNOPSIS dvid_raw(rawflag); int rawflag; LOGICAL flag (TRUE or FALSE) DESCRIPTION The dvid_raw() function determines how characters between 00h and 1fh will be treated. The display package defaults to a mode which treats characters such as carriage return and bell as true control characters, rather than values to be displayed. By calling this function with an argument of TRUE, any of these characters will be literally displayed, rather than interpreted as controls. Calling divd_raw(FALSE) restores normal operation. Does not have any effect if BIOS mode has been enabled. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_getmode() DV_REP.FNC - Thu 23 Nov 89 00:20 - Page 73: NAME dvid_rep -- write a repeated character PROTOTYPED IN: mflconio.h SYNOPSIS dvid_rep(ch, count); char ch; 8 bit character value int count; number of chars to write or repeat DESCRIPTION The dvid_rep() function will place a given number of a repeated character at the current internal cursor position. An alternate method is to use dvid_setcount() followed by dvid_putchr(). The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_setcount(), dvid_putchr() DV_SAY.FNC - Thu 23 Nov 89 00:20 - Page 74: NAME dvid_say -- display a string at specified position PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_say(row, col, string); int row, col; position to display char *string; string to display char ch; character to display DESCRIPTION This function uses the features of the MicroFirm Function Library's display package functions, and must therefore follow the rules laid down for their use. Specifically, dvid_init() must be called prior to using this function, and the function may fail if the target system is not a very close compatible since direct memory writing is being used. dvid_say() writes a string at the current real cursor position and then executes a dvid_flush() call before returning, thereby insuring cursor updating. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_say(0, 0, "Hello"); /* write to upper left corner */ for(i = 0; i < 10; i++) { dvid_char_at(i, i+1, i | '0'); /* write a sequence */ } dvid_move(12, 40); /* move to center of screen */ dvid_flush(); /* physically update screen cursor */ dvid_sayr(20, 70, "Goodby"); /* write into lower corner */ dvid_putc('!'); /* this char should be at 12, 40 */ SEE ALSO: d_say(), dvid_sayr(), dvid_char_at(), dvid_char_atr() DV_SAYR.FNC - Thu 23 Nov 89 00:20 - Page 75: NAME dvid_sayr -- dvid_say, returns cursor to starting point PROTOTYPED IN: mflconio.h SYNOPSIS void dvid_sayr(row, col, string); int row, col; position to display char *string; string to display char ch; character to display DESCRIPTION This function uses the features of the MicroFirm Function Library's display package functions, and must therefore follow the rules laid down for their use. Specifically, dvid_init() must be called prior to using this function, and the function may fail if the target system is not a very close compatible since direct memory writing is being used. dvid_sayr() writes a string at the current real cursor position. Before using this call, be sure the display package cursor position and the screen position are equal by doing a dvid_flush() call. EXAMPLE int i; dvid_init(); /* initialize the package */ dvid_cls(); /* clear the screen */ dvid_say(0, 0, "Hello"); /* write to upper left corner */ for(i = 0; i < 10; i++) { dvid_char_at(i, i+1, i | '0'); /* write a sequence */ } dvid_move(12, 40); /* move to center of screen */ dvid_flush(); /* physically update screen cursor */ dvid_sayr(20, 70, "Goodby"); /* write into lower corner */ dvid_putc('!'); /* this char should be at 12, 40 */ SEE ALSO: dvid_say(), d_say(), dvid_char_at(), dvid_char_atr() DV_SCRL.FNC - Thu 23 Nov 89 00:20 - Page 76: NAME dvid_scroll -- scroll a region of the screen PROTOTYPED IN: mflconio.h SYNOPSIS dvid_scroll(lines, srow, scol, erow, ecol, attrib); int lines; mode for region scroll int srow; starting row number int erow; ending row number int scol; starting column number int ecol; ending column number int attribute; video attribute DESCRIPTION The dvid_scroll() function scrolls a region of the screen. If the first argument is equal to 0 the region is cleared. If less than zero, the region is scrolled down. If greater than zero, scrolled up. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. DV_SETCT.FNC - Thu 23 Nov 89 00:20 - Page 77: NAME dvid_setcount -- set number of chars to write PROTOTYPED IN: mflconio.h SYNOPSIS dvid_setcount(count); int count; number of chars to write or repeat DESCRIPTION The dvid_setcount() function sets the number of times the NEXT character displayed will be actually displayed. Always is automatically restored to 1. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. SEE ALSO: dvid_putchr() DV_SETPG.FNC - Thu 23 Nov 89 00:20 - Page 78: NAME dvid_setpage -- set video page for writing, reading, and display PROTOTYPED IN: mflconio.h SYNOPSIS dvid_setpage(page, mode); int page; video page number 0-7 int mode; LOGICAL flag (TRUE or FALSE) DESCRIPTION The dvid_setpage() function is used ONLY with CGA cards, which may switch their video "pages". In 40 column modes, there are 8 pages numbered 0-7. In 80 column modes, there are 4 pages, numbered 0-3. Any page may be set for reading or writing, while setting a different or the same page for actual display. The (page) argument specifies the page number desired for writing, and is checked against the current video mode for correctness. The (mode) argument is 0 to select the page for writing/reading only, without changing the page current specified for display. (mode) set to 1 also changes the displayed page to the indicated (page). This function may therefore be used to alter not only the destination for direct memory writes, but also may be used to switch the display to the various pages. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. DV_SYNC.FNC - Thu 23 Nov 89 00:20 - Page 79: NAME dvid_sync -- enable or disable video sync PROTOTYPED IN: mflconio.h SYNOPSIS dvid_sync(mode); int mode; LOGICAL flag (TRUE or FALSE) DESCRIPTION The dvid_sync() function is used to control video synchronization on CGA cards. Normally, the functions default to sync enabled to prevent video "snow" during writes. (mode) may be set to FALSE to disable video sync. On some color cards, no snow will result evem without sync. For all cards, disabling sync will speed up access, although the resulting "snow" may be objectionable. N.B.: Often, there will be a little snow on the left edge of the screen, even with video sync enabled. Turning off the visible cursor using cursor_style() in this library can often eliminate the snow, which is actually caused by the cursor itself. The direct video access functions are described in some detail in the users manual accompanying the MicroFirm Function Library. They are only briefly reviewed here. Be sure to look at the utility file "dump.c" for examples of function usage. ENTERDAT.FNC - Thu 23 Nov 89 00:20 - Page 80: NAME enterdata -- enter a string of data from keyboard PROTOTYPED IN: mflconio.h SYNOPSIS r = enterdata(dest, qty, row, col, mode); int r; returns TRUE or FALSE char *dest; destination for string int qty; maximum allowable chars + 1 int row, col; row and column of string start* int mode; mode for character checking DESCRIPTION enterdata() provides a convenient method for entering character strings from the keyboard and verifying the character syntax. Line editing is supported to enhance user input. Entry is as follows: Carriage Return terminates input and returns TRUE. If no other data was entered, destination string is NULLed in the first position. CR is not placed into destination. ESCape terminates entry at once, NULLs destination, clears screen field, and returns FALSE. HOME clears field, and restarts entry without returning. BACKSPACE and Cursor Left will destructively backspace up to beginning of field. Only qty - 1 characters will be accepted. Any error sounds console BELL. Various modes allow for checking of syntax and mapping of characters : Mode 0: allow any printable character (ASCII 20H - 7FH) Mode 1: allow only alphabetics (A-Z, a-z) Mode 2: allow alphabetics and numerals only Mode 3: allow numerials only Mode 4: allow hexadecimal characters only (0-9, A-F, a-f) Modes 0, 1, and 2 will map lower case to upper case if decimal 128 (80H) is OR'd with the mode. * If row = -1, then current cursor position will be used, and col value i s ignored. ENTERDAT.FNC - Thu 23 Nov 89 00:20 - Page 81: EXAMPLE char string[31]; unsigned int num; d_pos(10, 20, 0); /* cursor to row 10, column 20 */ fputs("Enter an alphabetic string: ", stdout); if(!enterdata(string, 31, 10, 48, 1)) { fputs("\nESCape was pressed"); } else printf("\nString entered is %s\n", string); fputs("Enter hex value at current cursor position: ", stdout); if(!enterdata(string, 5, -1, 0, 4)) { fputs("\nESCape was pressed"); } else { num = atoi(string); printf("Number entered was %4x", num); } SEE ALSO: disp_enterdata() ENTERFN.FNC - Thu 23 Nov 89 00:20 - Page 82: NAME enterfn -- enter a filename from keyboard PROTOTYPED IN: mflconio.h SYNOPSIS void enterfn(dest, qty, row, col, allow); char *dest; destination for string int qty; maximum allowable chars + 1 int row, col; row and column of string start* int allow; TRUE to allow entension entry DESCRIPTION enterfn() provides a convenient method for entering a path and filename from the keyboard and verifying the character syntax. Line editing is supported to enhance user input. Entry is as follows: Carriage Return terminates input. If no other data was entered, destination string is NULLed in the first position. CR is not placed into destination. ESCape terminates entry at once, NULLs destination, and clears screen field. HOME clears field, and restarts entry without returning. BACKSPACE and Cursor Left will destructively backspace up to beginning of field. Only qty - 1 characters will be accepted. Any error sounds console BELL. If "allow" is TRUE, then a filename extension may be entered. Otherwise, no extension may be entered, since the period character will be disallowed. A drive may be specified; the colon is only allowed in the second character string position. EXAMPLE char string[31]; d_pos(10, 20, 0); /* cursor to row 10, column 20 */ fputs("Enter a filename: ", stdout); enterfn(string, 31, 10, 38, TRUE)); fputs("Enter filename at current cursor position: ", stdout); enterfn(string, 31, -1, 0, FALSE); * If row = -1, then current cursor position will be used, and col value is ignored. SEE ALSO: disp_enterfn() ERAOK.FNC - Thu 23 Nov 89 00:20 - Page 83: NAME eraok -- ask permission before overwriting existing file PROTOTYPED IN: mflfiles.h SYNOPSIS void eraok(filename); char *filename filename to test DESCRIPTION This function checks for the existance of the specified filename and if it exists, will ask the user (through stderr) if the file can be lost. If the user responds Y or y, the file is lost and return is made to the caller. If the response is anything else, the program aborts immediately, and the routine does NOT return to the caller. Exit is via the aabort() function of this library. EXAMPLE (assume argv[1] is string "foobar.com") eraok(argv[1]); printf("File %s has been deleted", argv[1]); ERROR.FNC - Thu 23 Nov 89 00:20 - Page 84: NAME error -- report a fatal error and exit PROTOTYPED IN: mflsys.h SYNOPSIS void error(string); char *string; error message to report DESCRIPTION This function sends the specified error message to stderr, and then exits through this library's aabort() function, sounding the console bell on its way out. EXAMPLE error("Invalid syntax"); SEE ALSO: aabort() EXISTS.FNC - Thu 23 Nov 89 00:20 - Page 85: NAME exists -- see if a file exists PROTOTYPED IN: mflfiles.h SYNOPSIS r = exists(name); int r; returns FALSE if not found, else TRUE char *name; filename to check DESCRIPTION If the specified filename, which may include drive and directory, is not found, then a value of zero (FALSE) is returned. Else, one (TRUE) is returned. This test does not take into consideration any attributes on the file, so that an fopen() call may still fail later. EXAMPLE if(exists("a:foo.bar")) puts("File exists!"); else puts("File does not exist"); SEE ALSO: access() EXIT2DOS.FNC - Thu 23 Nov 89 00:20 - Page 86: NAME exit2dos -- permission to exit program PROTOTYPED IN: mflfiles.h SYNOPSIS void exit2dos(); DESCRIPTION When invoked, this function clears the screen and places the message "Exit to DOS?" in the center of the display. The keyboard is read, and if the response is 'Y' or 'y', an aabort(0) function is called. For any other response, the function simply returns to the users program, which must then do whatever is necessary to continue with the program. EXAMPLE if(getche() == ESC) exit2dos(); /* watch for ESCape key */ else domorework(); EXPARG.FNC - Thu 23 Nov 89 00:20 - Page 87: NAME expand_arg -- expand command line wildcard filenames PROTOTYPED IN: mflfiles.h SYNOPSIS nargc = expand_arg(argc, argv); int nargc; no. of arguments in nargv int argc; no. of original arguments char *argv[]; original argument array extern char **nargv; expanded argument array DESCRIPTION The expand_arg() function is similar to UNIX exarg processing to expand wildcard filenames. This makes wildcard expansion totally transparent to the programmer. Most implementations of C compilers for MS-DOS don't provide this expansion. Therefore, if one command line argument is "*.ASM", this becomes one of the arguments to a program, instead of all files which will match the expansion. expand_arg() will take the (argc, argv) passed through the main() function, and make a new array, called (nargc, nargv) which will contain the expanded parameters. If there are no wildcards to expand, the new array winds up being the same as the old array. In addition, certain arguments will not be expanded, as they will be considered possible "options" or "literals". Any argument beginning with a hyphen (-), fraction bar (/), or single/double quote (" ') will not be expanded. Arguments beginning with a reverse slash (\) will be assumed to contain a directory name as part of a potential filename. Arguments will be expanded if they contain either of the wildcard characters (*) or (?). No matches to the specification will return no filenames. A filename without a wildcard designator will be passed to the new array without testing for existence. Filenames expanded will, of course, exist, or they wouldn't have been found. The label "nargc" is not a mandatory label. It is chosen merely for convenience in designating the new argument count. However, the array name "nargv" is a requirement, since the object module expand_arg defines that item. If you use the file "smdefs.h", the external reference to nargv will be done automatically, and you needn't worry about it. EXPARG.FNC - Thu 23 Nov 89 00:20 - Page 88: The expand_arg() function does dynamic memory allocation and re- allocation, and therefore should be called as the FIRST function after main(), and NEVER called again within the program. Violation of this requirement may cause some arguments to be lost if this function has to reallocate memory during expansion. Since wildcard expansion may result in more or less arguments than originally passed, nargc will seldom equal argc. It may be either larger or smaller. After calling expand_arg(), the variables nargc and nargv may be used anywhere you would normally have used argc and argv. If expand_arg() fails (usually a memory allocatiion problem), it will return a value of 0. No command line options would return 1, since the program name itself is a command line argument. EXAMPLE #include <stdio.h> #include <mflfiles.h> int nargc; main(int argc, char *argv[]) { int i; nargc = expand_arg(argc, argv); if(nargc == 0) error("Memory allocation error"); for(i = 0; i < nargc; i++) printf("Argument %d is %s\n", i, nargv[i]); } SEE ALSO: Demo WC.C EXTTYP.FNC - Thu 23 Nov 89 00:20 - Page 89: NAME exttyp -- check a filename for a particular extension PROTOTYPED IN: mflfiles.h SYNOPSIS r = exttyp(filename, extn); int r; returns TRUE if match, else FALSE char *filename filename to test char *extn extension string for match DESCRIPTION This function makes no changes to either entry parameter, but simply returns TRUE if the specified extension is found in the filename, or FALSE (0) if it is not. Case of the characters is ignored. The function is most useful to insure that a particular program will only use an extension of a specified type. EXAMPLE (assume argv[1] is string "foobar.com") if(exttyp(argv[1], "COM")) printf("File is executable"); else printf("File is not executable"); FCBCLOSE.FNC - Thu 23 Nov 89 00:20 - Page 90: NAME FCB_close -- close a file using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_close(f); int r; SUCCESS or ERROR struct xfcb *f; pointer to opened FCB to close DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. DOS has no provisions for creating or deleting a volume label using file handles. FCB_creat() will allow any type of file, even volume labels, to be created. Note that the file name may not contain any path information since DOS 1.0 (and CP/M before it) did not support nested subdirectories. You must therefore be in the same directory where the file is to be created. See pushdir() and popdir() for a convenient way to relocate to a directory where an FCB operation is to be performed. FCB_close() closes a previously opened FCB and deallocates its memory. EXAMPLE char buf[128]; struct XFCB my_fcb; if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) { FCB_reads(my_fcb,buf); /* read the 1st record */ FCB_readr(my_fcb,buf,7L); /* read the 7th record */ FCB_writes(my_fcb,buf); /* write the 8th record */ FCB_writer(my_fcb,buf,4L); /* write the 4th record */ } FCB_close(my_fcb); SEE ALSO: FCB_creat(), FCB_kill(), FCB_open() FCBCREAT.FNC - Thu 23 Nov 89 00:20 - Page 91: NAME FCB_creat -- create a file using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_creat(fname,attrib); int r; returns 0 if success, else ERROR char *fname; name of the file to create int attrib; attribute of the file to create DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. DOS has no provisions for creating or deleting a volume label using file handles. FCB_creat() will allow any type of file, even volume labels, to be created. Note that the file name may not contain any path information since DOS 1.0 (and CP/M before it) did not support nested subdirectories. You must therefore be in the same directory where the file is to be created. See pushdir() and popdir() for a convenient way to relocate to a directory where an FCB operation is to be performed. EXAMPLE struct FIND *ffblk; char *p; pushdir("C:\\"); /* go to the C: root directory */ /* next look for an old volume label to delete, but be */ /* aware that its filename may have to be fixed */ if (NULL != (ffblk = findfirst("*.*", FA_LABEL))) do { if (fflbk->attribute & FA_LABEL) break; } while (NULL != (ffblk = findnext())); if (ffblk) { if ('.' == ffblk->name[8]) /* not in a volume label */ strcpy(&ffblk->name[8], &ffblk->name[9]); FCB_kill(ffblk->name, FA_LABEL); } /* create a new volume label */ FCB_creat("A NEW LABEL", FA_LABEL); if (!chdir("PIRATED")) /* go to a subdirectory */ FCB_kill("*.*", 0); /* quickly wipe out all files */ popdir(); /* go back where we were */ SEE ALSO: FCB_kill(), FCB_open(), FCB_close() FCBKILL.FNC - Thu 23 Nov 89 00:20 - Page 92: NAME FCB_kill -- delete a file using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_kill(fname,attrib); int r; returns 0 if success, else ERROR char *fname; name of the file to delete int attrib; attribute of the file to delete DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. FCB_kill() is capable of deleting volume labels, which no other DOS function can do. Perhaps even more useful is it's capability to delete multiple wildcard-specified files. This is how DOS's own DEL and ERASE commands can delete entire groups of files so much more quickly than by using findfirst()/findnext() and unlink(). One note on the kill and create functions - You will notice than FCB_kill also requires an attribute parameter be passed to it. The reason for this is because volume labels break all the DOS rules for file naming. Both FCB_creat() and FCB_kill process file names quite differently when the file is known to be a volume label - which may contain spaces, and other characters illegal in DOS filenames. EXAMPLE struct FIND *ffblk; char *p; pushdir("C:\\"); /* go to the C: root directory */ /* next look for an old volume label to delete, but be */ /* aware that its filename may have to be fixed */ if (NULL != (ffblk = findfirst("*.*", FA_LABEL))) do { if (fflbk->attribute & FA_LABEL) break; } while (NULL != (ffblk = findnext())); if (ffblk) { if ('.' == ffblk->name[8]) /* not in a volume label */ strcpy(&ffblk->name[8], &ffblk->name[9]); FCB_kill(ffblk->name, FA_LABEL); } SEE ALSO: FCB_creat(), FCB_open(), FCB_close() FCBREADR.FNC - Thu 23 Nov 89 00:20 - Page 93: NAME FCB_readr -- random read using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_readr(f,buf,rec); int r; SUCCESS or ERROR struct xfcb *f; pointer to opened FCB char *buf; buffer to receive the data long rec; record number to read DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. FCB_readr() reads data from a previously opened file using FCBs. data are read as records of watever size was specified (if any - default is 128-byte records) in the the call to FCB_open(). FCB_readr() reads random records as specified in the calling parameters. EXAMPLE char buf[128]; struct XFCB my_fcb; if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) { FCB_reads(my_fcb,buf); /* read the 1st record */ FCB_readr(my_fcb,buf,7L); /* read the 7th record */ FCB_writes(my_fcb,buf); /* write the 8th record */ FCB_writer(my_fcb,buf,4L); /* write the 4th record */ } FCB_close(my_fcb); SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_reads(), FCB_writes(), FCB_writer() FCBREADS.FNC - Thu 23 Nov 89 00:20 - Page 94: NAME FCB_reads -- sequential read using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_reads(f,buf); int r; SUCCESS or ERROR struct xfcb *f; pointer to opened FCB char *buf; buffer to receive the data DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. FCB_reads() reads data from a previously opened file using FCBs. Data are read as records of watever size was specified (if any - default is 128-byte records) in the the call to FCB_open(). FCB_reads() reads records sequentially. EXAMPLE char buf[128]; struct XFCB my_fcb; if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) { FCB_reads(my_fcb,buf); /* read the 1st record */ FCB_readr(my_fcb,buf,7L); /* read the 7th record */ FCB_writes(my_fcb,buf); /* write the 8th record */ FCB_writer(my_fcb,buf,4L); /* write the 4th record */ } FCB_close(my_fcb); SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_readr(), FCB_writes(), FCB_writer() FCBWRITR.FNC - Thu 23 Nov 89 00:20 - Page 95: NAME FCB_writer -- random write using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_writer(f,buf,rec); int r; SUCCESS or ERROR struct xfcb *f; pointer to opened FCB char *buf; buffer containing the data to write long rec; record number to write DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. FCB_writer() writes data to a previously opened file using FCBs. Data are written as records of watever size was specified (if any - default is 128-byte records) in the the call to FCB_open(). FCB_writer() writes random records as specified in the calling parameters. EXAMPLE char buf[128]; struct XFCB my_fcb; if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) { FCB_reads(my_fcb,buf); /* read the 1st record */ FCB_readr(my_fcb,buf,7L); /* read the 7th record */ FCB_writes(my_fcb,buf); /* write the 8th record */ FCB_writer(my_fcb,buf,4L); /* write the 4th record */ } FCB_close(my_fcb); SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close() FCB_reads(), FCB_readr(), FCB_writes() FCBWRITS.FNC - Thu 23 Nov 89 00:20 - Page 96: NAME FCB_writes -- sequential write using a file control block PROTOTYPED IN: mflfiles.h SYNOPSIS r = FCB_writes(f,buf); int r; SUCCESS or ERROR struct xfcb *f; pointer to opened FCB char *buf; buffer containing the data to write DESCRIPTION With the advent of DOS 2.0, the File Control Block (FCB) method of file handling was superceded by the use of file handles. Even though rarely used, DOS retains the ability to process the older style FCB calls. This is normally of little interest except that there are still two functions which cannot be performed any way except by the use of FCBs. FCB_writes() writes data to a previously opened file using FCBs. Data are written as records of watever size was specified (if any - default is 128-byte records) in the the call to FCB_open(). FCB_writes() writes records sequentially. EXAMPLE char buf[128]; struct XFCB my_fcb; if (NULL != (my_fcb=FCB_open("fname.tmp", -1))) { FCB_reads(my_fcb,buf); /* read the 1st record */ FCB_readr(my_fcb,buf,7L); /* read the 7th record */ FCB_writes(my_fcb,buf); /* write the 8th record */ FCB_writer(my_fcb,buf,4L); /* write the 4th record */ } FCB_close(my_fcb); SEE ALSO: FCB_creat(), FCB_kill(), FCB_open(), FCB_close(), FCB_reads(), FCB_readr(), FCB_writer() FCOPY.FNC - Thu 23 Nov 89 00:20 - Page 97: NAME fcopy -- copy a file PROTOTYPED IN: mflfiles.h SYNOPSIS r = fcopy(from,to,over); int r; SUCCESS if file successfully copied, else ERROR char *from; file to copy char *to; destination of copy operation - may be a file name or a directory int over; overwrite permission, TRUE or FALSE DESCRIPTION The fcopy() function copies files just like the DOS COPY command. It also suffers some of the same limitations, e.g. the inability to overwrite protected files. It adds the extra security feature of requiring permission to overwrite an existing file. EXAMPLE char *file="FILE.EXT", *dest1="NEW_NAME.$$$", *dest2="NEW_DIR"; if (SUCCESS != fcopy(file,dest1,FALSE)) { printf("Can't copy %s to %s\n", file, dest1); if (SUCCESS == fcopy(file,dest1,TRUE)) puts("It already existed, but it's history now"); } if (SUCCESS != fcopy(file,dest2,FALSE)) printf("Can't copy %s to directory %s\n", file, dest2); SEE ALSO: rename() FCRYPT.FNC - Thu 23 Nov 89 00:20 - Page 98: NAME crypt_install -- install a stream encryption filter PROTOTYPED IN: mflfiles.h SYNOPSIS r = crypt_install(stream,key,lvl); int r; SUCCESS or ERROR SFILE *stream; stream to be filtered char *key; encryption/decryption key int lvl; zero for equivalence with crypt(), else the number of unique characters (1-26) required in the key DESCRIPTION The crypt_install() function is a special-purpose stream filter which allows data being read from or written to a stream to be encypted or decrypted "on the fly" transparently to the user. The sfinstall() function is called internally by crypt_install(). EXAMPLE SFILE *infile; infile = sfopen("file.ext", "r"); /* input from a file */ crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */ sfinstall(infile, ucase_filt); /* after converting to UC */ SEE ALSO: crypt(), cryptqual(), sfopen(), scopen(), sclose(), sfinstall(), ucase_filt, lcase_filt FILLCH.FNC - Thu 23 Nov 89 00:20 - Page 99: NAME fillch -- fill a string with a character PROTOTYPED IN: mflstrng.h SYNOPSIS void fillch(dest, chr, qty); char *dest destination string char chr character to place int qty number to place DESCRIPTION This function fills string "dest" with "qty" number of characters "chr". The destination string must be large enough to hold the indicated quantity, as no check is made. In addition, a NULL is not placed after the last character. EXAMPLE char string[20]; fillch(string, 'A', 19); string[20] = NULL; makes a usable string of 19 "A" characters. FLN_FIX.FNC - Thu 23 Nov 89 00:20 - Page 100: NAME fln_fix -- remove "dot" directories from pathnames PROTOTYPED IN: mflfiles.h SYNOPSIS path = fln_fix(path); char *path; pathname to "scrunch" DESCRIPTION fln_fix() is called internally by flnorm() and can be used alone though it is a somewhat dumber, yet still useful function than flnorm(). Simply, fln_fix(), when passed a filename, ignores the drive designation (i.e. "D:") and returns the same pathname, processed in place, with all "dot" directories scrunched out. Note that fln_fix() has no error return condition and always tries to fix whatever filename it's passed. Basically, fln_fix() does the following: 1. Ignores all leading drive specs including network specs where the colon (":") may not be the second character. 2. Calls unix2dos() to convert Unix-style filenames (i.e. using the "/" character as a path separator) to DOS-style. 3. Leading backslashes, indicating the root directory are ignored. If the root directory is specified, parent directory (double- dot - "..") subdirectories are ignored. 4. Any doubled backslashes are converted to single backslashes. 5. Single dot (".") directories are scrunched. 6. Embedded double-dot directories are scrunched to remove the preceding redundant level. 7. Trailing backslashes are preserved. Also internally, the flnorm() function calls unix2dos() which simply converts Unix-style path names (using '/' as the path separator) to DOS-style (using '\' as the path separator). EXAMPLE char norml[MAX_FLEN]; /* defined in MFLDEFS.H */ if(flnorm(".\\..\\xyz\\..\\abc\\pdq",char_norml) { puts("unable to normalize filename"); /* NOTE: even if pdq doesn't exist, if the rest of the path can be normalized, "\PDQ" will be appended and no error will be returned */ if(flnorm(".\\..\\xyz\\..\\abc\\pdq\\",char_norml) { puts("bad path or not a directory"); puts(fln_fix("abc/123.4:/stuff/../.././junk/./garbage"); /* Prints "abc/123.4:\JUNK\GARBAGE" */ puts(unix2dos("unix_dos/style/path/name.ext")); /* Prints "UNIX_DOS\STYLE\PATH\NAME.EXT" */ SEE ALSO: flnorm(), unix2dos() FLNORM.FNC - Thu 23 Nov 89 00:20 - Page 101: NAME flnorm -- normalize a filename PROTOTYPED IN: mflfiles.h PORTABILITY: flnorm() is similar to functions included in many standard libraries as well as many 3rd party libraries. Many of thes functions, however, rely on DOS calls introduced with DOS 3.0 and will therefore not work on systems running DOS 2.xx. SYNOPSIS r = flnorm(path,norml); int r; returns zero if valid, else ERROR char *path; pathname to normalize char *norml; buffer to receive normalized name DESCRIPTION DOS allows filenames and pathnames to be specified in a bewildering variety of ways. Drive letters are optional, the two types of "dot" directories may be freely interspersed in the name, and the path may either be referenced to the current directory or the root. The primary function of flnorm() is to determine if a file MAY exist. The drive and path (if present) are validated to see if the named file may be created or opened. As a secondary function, path names passed to flnorm() with a trailing path delimiter ('\' or '/') are further validated to verify that they exist and are directories. Specifically, flnorm() "normalizes" file/path names according to the following rules: 1. Filenames are first checked to see if they exist. 2. If a drive is specified, drvalid() is called to verify it. 3. If the filename doesn't exist, but is on a valid drive, the pathname is extracted and it is checked. 4. If the pathname is valid, it is normalized and the file name reattached. 5. If the specified filename ends in a "\", it is assumed to be a directory. If a file of the specified name is found, an error is returned. 6. If nothing in the filename may be verified, an error status is returned and the return filename is blanked. The normalized filename is always of the form "D:\PATH\FILE" even if "FILE" is specified as and found to be a directory. A dangling "\" is only returned for the root directory. FLNORM.FNC - Thu 23 Nov 89 00:20 - Page 102: EXAMPLE char norml[MAX_FLEN]; /* defined in MFLDEFS.H */ if(flnorm(".\\..\\xyz\\..\\abc\\pdq",char_norml) { puts("unable to normalize filename"); /* NOTE: even if pdq doesn't exist, if the rest of the path can be normalized, "\PDQ" will be appended and no error will be returned */ if(flnorm(".\\..\\xyz\\..\\abc\\pdq\\",char_norml) { puts("bad path or not a directory"); SEE ALSO: fln_fix, unix2dos FLREMVOL.FNC - Thu 23 Nov 89 00:20 - Page 103: NAME flremvol -- removes the volume label on a specified disk drive PROTOTYPED IN: mflfiles.h PORTABILITY: Compatible with Blaise (tm) library functions of the same name. SYNOPSIS r = flremvol(drv); int r; SUCCESS or ERROR char drv; the drive letter (A-Z, a-z) whose volume label to remove DESCRIPTION The flremvol() function removes the volume label from any valid disk drive. EXAMPLE if (ERROR == flremvol('C')) puts("cant remove volume label from drive C:"); SEE ALSO: flretvol(), flsetvol() FLRETVOL.FNC - Thu 23 Nov 89 00:20 - Page 104: NAME flretvol -- get the volume label for a disk drive PROTOTYPED IN: mflfiles.h PORTABILITY: Compatible with Blaise (tm) library functions of the same name. SYNOPSIS r = flretvol(drv); char *r; the volume label or NULL if no label or an error char drv; the drive letter to check (A-Z, a-z) DESCRIPTION The flretvol() function retrieves the volume label for any valid disk drive. The returned volume label will be an ASCIIZ string, 1-11 characters long, uppercase, and without the usual filename period between the 8th and 9th characters. EXAMPLE char *vlbl; if (NULL == (vlbl = flretvol('C'))) puts("cant retrieve volume label from drive C:"); else printf("volume label of C: is %s\n", vlbl); SEE ALSO: flremvol(), flsetvol() FLSETVOL.FNC - Thu 23 Nov 89 00:20 - Page 105: NAME flsetvol -- sets the volume label on a specified disk drive PROTOTYPED IN: mflfiles.h PORTABILITY: Compatible with Blaise (tm) library functions of the same name. SYNOPSIS r = flsetvol(drv,vlbl); int r; SUCCESS or ERROR char drv; the drive letter (A-Z, a-z) whose volume label to set char *vlbl; new volume label to set DESCRIPTION The flsetvol() function set the volume label on any valid disk drive. If a volume label already exists for that drive, it is deleted. The specified label may be upper or lower case, but will be converted to upper case by DOS. EXAMPLE if (ERROR == flsetvol('C',"new_label")) puts("cant set volume label on drive C:"); SEE ALSO: flretvol(), flremvol() FNMERGE.FNC - Thu 23 Nov 89 00:20 - Page 106: NAME fnmerge -- merge drive/path/file/ext into a file string PROTOTYPED IN: mflfiles.h PORTABILITY: fnmerge() is a superset of a function of the same name available in and TC SYNOPSIS void fnmerge(s1,s2,s3,s4,s5,s6,s7); char *s1; buffer for file string char *s2; drive char *s3; drive+path char *s4; path char *s5; name+ext char *s6; name char *s7; ext DESCRIPTION The fnmerge() function takes the same sort of arguments as fnsplit() and merges them to create a file name string. Note that not all inputs are required. For example, if the drive+path is given, the individual drive and path specs are ignored. This assures compatibility with basename(). If the name+ext spec is given, the individual name and extension specs are ignored. If a path is give, either individually or included with a drive spec, and does not include a terminating '\', one is appended. If a separate extension spec is given, it may include a leading '.' or not - one will be added if not. Finally, fnmerge() calls unix2dos() to convert all embedded '/'s into '\'s. As with fnsplit, other compiler implementations may be mimicked with macros. EXAMPLE char file[MAX_FLEN]; char *pname = "c:/use/this"; char *drive = "z:"; char *path = "not/this/"; char *fname = NULL; /* or = ""; */ char *name = "name"; char *ext = "ext"; /* leading '.' is optional */ fnmerge(file,drive,pname,path,fname,name,ext); after execution file is "C:\USE\THIS\NAME.EXT" SEE ALSO: basename(), fnsplit() FNSPLIT.FNC - Thu 23 Nov 89 00:20 - Page 107: NAME fnsplit -- split a string into drive/path/file/ext PROTOTYPED IN: mflfiles.h PORTABILITY: fnsplit() is a superset of a function of the same name available in and TC SYNOPSIS r=fnsplit(s1,s2,s3,s4,s5,s6,s7); int r; bit map of file string features bit 0 - Extension was specified bit 1 - Filename was specified bit 2 - Directory was specified bit 3 - Drive was specified bit 4 - Wildcards were specified in filename bit 5 - Wildcards were specified in path char *s1; original string char *s2; destination for drive char *s3; destination for drive+path char *s4; destination for path char *s5; destination for name+ext char *s6; destination for name char *s7; destination for ext DESCRIPTION The fnsplit() function requires more setup effort than basename() but returns more information. In addition to ALL of the information returned by basename(), fnsplit() also returns the drive specification and separates the filename into name and extension components. As with basename(), if any component isn't specified, an empty string (i.e. first character = '\0') is returned for that component. As a side effect, fnsplit() calls unix2dos() which converts all '/' characters to '\' characters. A NULL passed for any argument will be ignored, allowing simple macro emulation of other compilers' implementations of fnsplit(). Internally, fnsplit() calls has_wild() which checks for the existence of DOS wildcard characters ('*' and '?') in the path and filename portions of the given string. FNSPLIT.FNC - Thu 23 Nov 89 00:20 - Page 108: EXAMPLE char *name[] = "C:\looney\bin\wumpus.com"; char path[MAX_FLEN], file[13]; char drive[3], pname[MAX_FLEN], fname[9], ext[4]; fnsplit(name, drive, pname, path, file, fname, ext); after execution, fnsplit returns 0x0f, arrays are as follows: name (unchanged except '/'s converted to '\'s) drive C: pname C:\looney\bin\ path \looney\bin\ file wumpus.com fname wumpus ext .com SEE ALSO: basename(), fnmerge(), has_wild() FOPEND.FNC - Thu 23 Nov 89 00:20 - Page 109: NAME fopend -- fopen a file in an environment variable PROTOTYPED IN: mflfiles.h SYNOPSIS fd = fopend(name, mode, envar); FILE *fd; char *name; filename char *mode; mode char *envar; name of environment variable DESCRIPTION This function allows the opening of a file in other than just the current directory. It will attempt to do the open in the current directory first, and if that fails, will then expand to search according to a a specified environment variable. fopend will return NULL a pointer upon failure. EXAMPLE FILE *fd; if((fd = fopend("stdio.h", "r", "INCLUDE")) == NULL) cant("stdio.h"); else puts("stdio.h is open for reading"); SEE ALSO fopenp(), fopeng() FOPENG.FNC - Thu 23 Nov 89 00:20 - Page 110: NAME fopeng -- fopend/fopenp combination PROTOTYPED IN: mflfiles.h SYNOPSIS fd = fopeng(name, mode, envar); FILE *fd; char *name; filename char *mode; mode char *envar; name of environment variable DESCRIPTION This function allows the opening of a file in other than just the current directory. It will attempt to do the fopen in the current directory first, and if that fails, will then expand to search by performing a fopend() first and upon failure an fopenp(). See these functions for details. EXAMPLE FILE *fd; if((fd = fopeng("stdio.h", "r", "INCLUDE")) == NULL) cant("stdio.h"); else puts("stdio.h is open for reading"); SEE ALSO: fopenp(), fopend() FOPENP.FNC - Thu 23 Nov 89 00:20 - Page 111: NAME fopenp -- fopen a file in the PATH PROTOTYPED IN: mflfiles.h SYNOPSIS fd = fopenp(name, mode); FILE *fd; char *name; filename char *mode; mode char *envar; name of environment variable DESCRIPTION This function allows the opening of a file in other than just the current directory. It attempts to do the fopen in the current directory first, and if that fails, will then expand to search along PATH environment variable. It returns a NULL pointer upon failure. EXAMPLE FILE *fd; if((fd = fopenp("foo.bar", "r")) == NULL) cant("foo.bar"); else puts("File is now opened!"); SEE ALSO fopend(), fopeng() FTRUNC.FNC - Thu 23 Nov 89 00:20 - Page 112: NAME ftrunc -- truncate an fopen'ed file PROTOTYPED IN: mflfiles.h SYNOPSIS result = ftrunc(fp,posn); int result; SUCCESS or ERROR FILE *fp; file descriptor of file to truncate long posn; size of truncated file DESCRIPTION The ftrunc() function will truncate a file that has been opened as a standard stream. It will return an ERROR if the truncation length is longer than the existing file. EXAMPLE int fd; FILE *fp; char *fname; long size = 100L; fp = fopen(fname, "wb"); ftrunc(fp, size); SEE ALSO: trunc(), truncate() GETCODE.FNC - Thu 23 Nov 89 00:20 - Page 113: NAME get_code_adr -- get a function address PROTOTYPED IN: mflsys.h SYNOPSIS void get_code_adr(function, segment, offset); int *function; name of function int *segment; destination of segment value int *offset; destination of offset value DESCRIPTION This function is used to get the absolute segment and offset values for the address of a function within a program. It is useful for installing interrupt handlers and interfacing to assembly language modules. EXAMPLE somefunc() { } main() { int segment, offset; get_code_adr(&somefunc, &segment, &offset); printf("Address is %x:%x\n", segment, offset); } SEE ALSO: get_data_adr() GETDATA.FNC - Thu 23 Nov 89 00:20 - Page 114: NAME get_data_adr -- get a data item address PROTOTYPED IN: mflsys.h SYNOPSIS void get_data_adr(item, offset, segment); int *item; name of data item int *offset; destination of offset value int *segment; destination of segment value DESCRIPTION This function is used to get the absolute segment and offset values for the address of a data item within a program. It is useful for installing interrupt handlers and interfacing to assembly language modules. EXAMPLE int somenumber; main() { int segment, offset; get_data_adr(&somenumber, &offset, &segment); printf("Address is %x:%x\n", segment, offset); } SEE ALSO: get_code_adr() GETDRV.FNC - Thu 23 Nov 89 00:20 - Page 115: NAME getdrv -- return default drive PROTOTYPED IN: mflfiles.h SYNOPSIS r = chdrv(drive); int r; returns ERROR if drive is invalid char drive; drive ('A' - 'Z') to check DESCRIPTION Getdrv() is an analog of the getcwd() function which returns the default drive letter rather than the default directory. Note that the drive letter returned by getdrv() is always upper case. EXAMPLE char drive; printf("currently on drive %c:\n", drive = getdrv()); if ('C' != drive) { if (!chdrv('C')) puts("changed to drive C:"); else puts("\aunable to change drives"); } SEE ALSO: drvalid(), chdrv() GETFT.FNC - Thu 23 Nov 89 00:20 - Page 116: NAME get_filetime -- get file date/time stamp PROTOTYPED IN: mfltime.h SYNOPSIS #include <time.h> void get_filetime(ptm, fh); struct tm *ptm; pointer to tm structure int fh; file handle of opened file DESCRIPTION The get_filetime() function fteches the date/time of a file. The data from the file is placed in the specified time structure (see "time.h"), in the same format as used by other time functions by. The file must be opened, and a file handle passed, NOT a FILE pointer. No error is returned from this function. The structure elements tm_wday and tm_yday are always returned as 1, as they are generally irrelevant for file dates. They can subsequently be calculated from the other information. EXAMPLE #include <time.h> #include <mflfiles.h> FILE *fp; char *string; struct tm *stamp; /* report the date/time of a specified file on command line */ main(int argc, char *argv[]) { if(2 != argc) exit(0); if(NULL == (fd = fopen(argv[1], "r"))) exit(0); /* note conversion of FILE *fd to file handle next: */ get_filetime(stamp, (fileno(fd))); fclose(fd); string = asctime(stamp); printf("File %s modified on %s\n", argv[1], string); } SEE ALSO: getftime() GETFTIME.FNC - Thu 23 Nov 89 00:20 - Page 117: NAME getftime -- get a file's time/date stamp PROTOTYPED IN: mfltime.h PORTABILITY: TC SYNOPSIS r = getftime(fh, t); int r; returns 0 if successful, else -1 and sets errno int fh; handle of file to check struct ftime *t; pointer to file time/date stamp structure DESCRIPTION This routine retrieves a file's time/date stamp. See MFLTIME.H for a description of the ftime structure. EXAMPLE struct ftime stamp; int fh; fh = open ("file.ext", O_RDONLY); if (ERROR == getftime(fh, &stamp)) puts("can't read time/date stamp"); printf("FILE.EXT was @ %02d-%02d-%02d %02d:%02d:%02d\n", stamp.ft_month, stamp.ft_day, stamp.ft_year + 80, stamp.ft_hour, stamp.ft_min, stamp.ft_tsec * 2); SEE ALSO: setftime, touch, get_filetime GETKEY.FNC - Thu 23 Nov 89 00:20 - Page 118: NAME getkey -- extended keyboard fetch PROTOTYPED IN: mflconio.h SYNOPSIS #include "keys.h" r = getkey(); int r; returns keyboard value DESCRIPTION This function eases the reading of all keys, whether normal or function keys. The getch() function is used to return a keyboard value. If the first value received is 0, then a second value is fetched and 256 (0x100) is added to flag the return value as an extended function key. The calling program should check for a return value greater than 255. If true, subtract 256 (or "and" with 0xff) and consider the result as a function key. Most function keys are defined in keys.h, and others may be user added. EXAMPLE This example tests for function key 3 (FK3) #include "keys.h" int r; while(TRUE) { r = getkey(); if(r < 256) { printf("Not FK3 key"); continue; } else r &= 0xff; if(r == FK3) printf("FK3 sensed!!!"); } GETPATH.FNC - Thu 23 Nov 89 00:20 - Page 119: NAME getpath -- retrieve the PATH variable and parse PROTOTYPED IN: mflfiles.h SYNOPSIS c = getpath(string); int c; count of characters returned in string char *string[]; destination for parsed string. Minimum 128 bytes, but longer paths could clobber this. DESCRIPTION This function extracts the PATH variable (if it exists) and makes a "pseudo-array" at destination string. All semi-colon separators are replaced by NULL bytes. The returned integer count totals all characters inserted into the string including NULLS, and should be used to determine the exact end of the string, since a NULL byte will not determine this. EXAMPLE char *string[135]; int count; count = getpath(string); count will return as zero if no PATH is found. GETPOS.FNC - Thu 23 Nov 89 00:20 - Page 120: NAME getpos -- get current cursor position PROTOTYPED IN: mflconio.h SYNOPSIS position = getpos(page); unsigned int position; returned position int page; video page to check DESCRIPTION Returns the row and column of the cursor on the specified video page. Row is in upper 8 bits of returned integer and column in lower 8 bits. Values are in binary. EXAMPLE unsigned int position; short row, column; position = getpos(0); /* on video page 0 */ row = (position >> 8) & 0xff; column = position & 0xff; SEE ALSO: d_pos() GETPREES.FNC - Thu 23 Nov 89 00:20 - Page 121: NAME get_press -- get waiting keypress PROTOTYPED IN: mflsys.h SYNOPSIS r = get_press(); get waiting keypress unsigned char r; key value DESCRIPTION This is part of a series of functions is used to read and debounce the four switch inputs on the joystick input port. The analog joystick inputs are not supported. get_press() is called to return any fully debounced input. A value of 0 indicates no input available. Switch values are returned as an 8 bit value, with only the lowest 4 bits in use. A set bit indicates a closed switch. If multiple keystrokes are not allowed, then get_press() will return 0, 1, 2, 4, or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be returned. bit position pin number on connector 0 2 1 7 2 14 3 10 EXAMPLE main() { unsigned char i; init_game(FALSE); /* allow only single switch inputs */ for ever() { debounce(); /* call this regularly */ i = get_press(); if(i is 0) continue; printf("switch value is %x\n", i); } } SEE ALSO: init_game(), clear_game(), debounce() GETPRESS.FNC - Thu 23 Nov 89 00:20 - Page 122: NAME get_press -- get waiting keypress PROTOTYPED IN: mflsys.h SYNOPSIS r = get_press(); get waiting keypress unsigned char r; key value DESCRIPTION This is part of a series of functions is used to read and debounce the four switch inputs on the joystick input port. The analog joystick inputs are not supported. get_press() is called to return any fully debounced input. A value of 0 indicates no input available. Switch values are returned as an 8 bit value, with only the lowest 4 bits in use. A set bit indicates a closed switch. If multiple keystrokes are not allowed, then get_press() will return 0, 1, 2, 4, or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be returned. bit position pin number on connector 0 2 1 7 2 14 3 10 EXAMPLE main() { unsigned char i; init_game(FALSE); /* allow only single switch inputs */ for ever() { debounce(); /* call this regularly */ i = get_press(); if(i is 0) continue; printf("switch value is %x\n", i); } } SEE ALSO: init_game(), clear_game(), debounce() GETPRTSC.FNC - Thu 23 Nov 89 00:20 - Page 123: NAME getPrtSc_stat -- retrieves status of last PrtSc operation PROTOTYPED IN: mflsys.h SYNOPSIS r = getPrtSc_stat(); int r; 0 if successful, 1 if screen printing is already in process, -1 if the last screen print operation failed DESCRIPTION The getPrtSc_stat() function checks on the activity of any previous calls to PrtSc(). EXAMPLE if (0 == getPrtSc_stat()) /* make sure not already printing */ PrtSc(); SEE ALSO: PrtSc() GTODFUNC.FNC - Thu 23 Nov 89 00:20 - Page 124: NAME gtodsub -- Get time of day to file pointer PROTOTYPED IN: mfltime.h SYNOPSIS void gtodsub(fp); FILE *fp; void gtodstr(str); char *str; DESCRIPTION This function reads the system date and time and sends them in a formatted string to the specified output channel, or to a string. EXAMPLE gtodsub(stdout); /* send date/time to stdout */ char string[30]; gtodstr(string); printf("date and time are %s\n", string); /* same result */ SEE ALSO: gtodstr GTODSTR.FNC - Thu 23 Nov 89 00:20 - Page 125: NAME gtodstr -- Get time of day to a string PROTOTYPED IN: mfltime.h SYNOPSIS void gtodstr(str); char *str; DESCRIPTION This function reads the system date and time and sends them in a formatted string to the specified output channel, or to a string. EXAMPLE char string[30]; gtodstr(string); printf("date and time are %s\n", string); /* same result */ SEE ALSO: gtodsub() GTODSUB.FNC - Thu 23 Nov 89 00:20 - Page 126: NAME gtodsub -- Get time of day to file pointer PROTOTYPED IN: mfltime.h SYNOPSIS void gtodsub(fp); FILE *fp; DESCRIPTION This function reads the system date and time and sends them in a formatted string to the specified output channel, or to a string. EXAMPLE gtodsub(stdout); /* send date/time to stdout */ SEE ALSO: gtodstr() HAS_WILD.FNC - Thu 23 Nov 89 00:20 - Page 127: NAME has_wild -- checks a string for DOS wildcards PROTOTYPED IN: mflfiles.h SYNOPSIS r=has_wild(str); int r; TRUE if str contains '*' or '?', else FALSE char *str; string to check DESCRIPTION The has_wild() function checks for the existence of DOS wildcard characters ('*' and '?') in a string. It is used internally by fnsplit(). EXAMPLE if (has_wild("TEST.FIL")) /* returns FALSE */ ... if (has_wild("TE?T.FIL")) /* returns TRUE */ ... if (has_wild("TEST*.FIL")) /* returns TRUE */ ... SEE ALSO: fnsplit() HSTR_I.FNC - Thu 23 Nov 89 00:20 - Page 128: NAME hstr_i -- make an ascii hexadecimal string into an integer PROTOTYPED IN: mflstrng.h SYNOPSIS c = hstr_i(p); char *p; string of ascii characters unsigned int c; returned hex value DESCRIPTION Read a string of ascii hexadecimal digits (0-9, A-F) and create an integer from the result. String must begin with a hex digit. Calculation proceeds to first non-hex digit or NULL terminator. EXAMPLE char string[] = "1A5C*"; int result; result = hstr_i(string); /* result will equal 0x1A5C */ I_DSTR.FNC - Thu 23 Nov 89 00:20 - Page 129: NAME i_dstr -- make an integer from a decimal ascii string PROTOTYPED IN: mflstrng.h SYNOPSIS c = i_dstr(p, r); char *p; destination string pointer int r; integer to convert int c; count of characters in string DESCRIPTION Convert an integer into an ascii decimal string (unsigned). Range is that of 16 bits unsigned, or 0-65535. The function returns the number of characters placed in the string. The string is NULL terminated, and must be at least six bytes long to accomodate the longest number plus the NULL. Numbers are assumed to be positive. EXAMPLE char string[6]; int count; count = i_dstr(string, 1357); count will equal 4 string will be "1357\0" IBMTYPE.FNC - Thu 23 Nov 89 00:20 - Page 130: NAME ibmtype -- find out type of computer PROTOTYPED IN: mflsys.h SYNOPSIS r = ibmtype(); int r; r = 0 for PC or XT, 1 for PC Jr., 2 for AT, 3 for unknown type DESCRIPTION This function examines the byte in ROM at F000:FFFEh. For real IBM computers, this should be: 0xff PC 0xfe XT 0xfd JR 0xfc AT Many close clones will also encode this byte in the above manner, although there is no requirement for this feature. CAVEAT The results of this test should be taken with a grain of salt the size of Salt Lake City. Even IBM has shipped XTs with the PC id byte. The NOVAS AT clone correctly has 0xfc, but the Z-NIX XT clone (which is a very close clone) has 0x05. Don't depend too heavily on the results being really accurate. EXAMPLE r = ibmtype(); if(r == 2) printf("This machine is an AT, maybe!"); INDEX.FNC - Thu 23 Nov 89 00:20 - Page 131: NAME index -- offset of leftmost char in a string DEFINED IN: mflstrng.h SYNOPSIS r = index(s,c); int r; offset (index) of leftmost occurance of char c in string s, -1 if unsuccessful char *s; string to search char c; character for which to search DESCRIPTION This function is part of a set of macros included in MFLSTRNG.H. Index returns the leftmost character offset in a string. Note that index() is available as functions in many systems and may return an integer offset, as done here, or may simply be aliases for strchr() and chrrchr(), respectively. It is provided here to aid portability, but may need to be modified or undefined depending on the original implementation. EXAMPLES int offset; offset=index("ABCDEDCBA", 'C'); /* returns 2 */ offset=index("ABCDEDCBA", 'Q'); /* returns -1 */ SEE ALSO: rindex() INITGAME.FNC - Thu 23 Nov 89 00:20 - Page 132: NAME init_game -- initialize and set game port mode PROTOTYPED IN: mflsys.h SYNOPSIS (void)init_game(mode); DESCRIPTION This is part of a series of functions used to read and debounce the four switch inputs on the joystick input port. The analog joystick inputs are not supported. init_game() is called to setup the processor. If its argument is TRUE, then multiple key inputs are allowed. If FALSE, any multiple key closure will be locked out. The game port was originally intended for playing games via an arcade-style joystick. However, for the serious engineer, this port is an excellent "quick and dirty" 4 bit TTL level input port. It may be used for reading external switches, sensors, etc. Switch values are returned as an 8 bit value, with only the lowest 4 bits in use. A set bit indicates a closed switch. If multiple keystrokes are not allowed, then get_press() will return 0, 1, 2, 4, or 8. If multiples are allowed, then all values 0-15 (0-0x0f) may be returned. bit position pin number on connector 0 2 1 7 2 14 3 10 EXAMPLE main() { unsigned char i; init_game(FALSE); /* allow only single switch inputs */ for ever() { debounce(); /* call this regularly */ i = get_press(); if(i is 0) continue; printf("switch value is %x\n", i); } } SEE ALSO: clear_game(), get_press(), debounce() INSTICK.FNC - Thu 23 Nov 89 00:20 - Page 133: NAME installtick -- install a timer interrupt service routine PROTOTYPED IN: mfltime.h SYNOPSIS void installtick(&counter); unsigned int counter; integer to decrement DESCRIPTION "ticker" is not actually a C function, but a routine which is installed on interrupt 1CH. At each interrupt (18.21 times per second) this routine decrements an integer (16 bits) whose address was passed during installation. The C program can load and test this integer at any time to perform time-based operations. When the variable is decremented to zero, it is not decremented any further; i.e., no underflow occurs. Therefore, the integer is actually an unsigned integer with a maximum count of 65535, or (65535/18.2) seconds. installtick() installs the ticker on interrupt 1CH and saves the address of the passed variable. removetick() restores the interrupt 1CH vector to its original state. Any other routines already installed on this vector are executed after ticker, since the ticker chains to the original vector after execution. EXAMPLE int counter; main() { installtick(&counter); counter = 18 * 10; /* about 10 seconds */ while(counter > 0); /* delay here */ removetick(); } CAVEAT It is imperative to call removetick() BEFORE terminating the program, Otherwise, the system will crash! SEE ALSO: ctlbrk(), criterr(), removetick() ISCONS.FNC - Thu 23 Nov 89 00:20 - Page 134: NAME iscons -- is file descriptor the console PROTOTYPED IN: mflconio.h SYNOPSIS r = iscons(fd); int r; TRUE or FALSE returned FILE *fd; file descriptor to check DESCRIPTION The specified file descriptor is tested to see if it refers to the console device. TRUE (not 0) is returned if it does, and FALSE (0) otherwise. This is a test primarily aimed at detecting if stdin or stdout have been redirected away from the default console. EXAMPLE if(iscons(stdin)) puts("stdin is the keyboard"); else ("stdin is probably a file"); ISLEAP.FNC - Thu 23 Nov 89 00:20 - Page 135: NAME isleap -- check if year is a leap year PROTOTYPED IN: mfltime.h SYNOPSIS r = isleap(year); unsigned r; returns TRUE if leapyear, else FALSE unsigned year; year value DESCRIPTION The isleap() function simply checks the specified year to return a TRUE if the specified year is a leap year. EXAMPLE if(isleap(1986)) printf("This is a leap year"); else printf("This is not a leap year"); SEE ALSO: ymd_to_julian, julian_to_ymd, julian_to_wkday, julian_to_yrday julian_to_dayname, julian_to_time, julian_to_tm, time_to_julian tm_to_julian ISQRT.FNC - Thu 23 Nov 89 00:20 - Page 136: NAME isqrt -- extract integer square root of an int PROTOTYPED IN: mflmath.h SYNOPSIS result = isqrt(number); int result; square root (truncated) unsigned number; number whose square root to extract DESCRIPTION This part of a set of routines provided primarily for embedded systems programmers. These routines extract the square root of either a short or long integer number without the use of floating point math. Versions are provided which will either truncate or round the result. Note that arguments are unsigned so no error checking is done for negative inputs. EXAMPLE int i; for (i = 4; i < 9; ++i) printf("sqrt(%d) = %d, %d\n", i, isqrt(i), isqrtr(i)); /* prints: sqrt(4) = 2, 2 sqrt(5) = 2, 2 sqrt(6) = 2, 2 sqrt(7) = 2, 3 sqrt(8) = 2, 3 sqrt(9) = 3, 3 */ SEE ALSO: isqrtr(), lsqrt(), lsqrtr() ISQRTR.FNC - Thu 23 Nov 89 00:20 - Page 137: NAME isqrtr -- extract integer square root of an int w/ rounding PROTOTYPED IN: mflmath.h SYNOPSIS result = isqrtr(number); int result; square root (rounded) unsigned number; number whose square root to extract DESCRIPTION This is part of a set of routines provided primarily for embedded systems programmers. These routines extract the square root of either a short or long integer number without the use of floating point math. Versions are provided which will either truncate or round the result. Note that arguments are unsigned so no error checking is done for negative inputs. EXAMPLE int i; for (i = 4; i < 9; ++i) printf("sqrt(%d) = %d, %d\n", i, isqrt(i), isqrtr(i)); /* prints: sqrt(4) = 2, 2 sqrt(5) = 2, 2 sqrt(6) = 2, 2 sqrt(7) = 2, 3 sqrt(8) = 2, 3 sqrt(9) = 3, 3 */ SEE ALSO: isqrt(), lsqrt(), lsqrtr() JUL2DNAM.FNC - Thu 23 Nov 89 00:20 - Page 138: NAME julian_to_dayname -- convert Julian date to day of the week PROTOTYPED IN: mfltime.h SYNOPSIS r = julian_to_dayname(julian); char *r; day of week ("Monday", "Tuesday", etc.) long julian; Julian (scalar) date DESCRIPTION This function returns a string representing the name of the day on which a given scalar (Julian) date occured. The string returned is taken from the active locale. EXAMPLE long jday; printf("Julian date %ld fell on a %s\n", jday, julian_to_dayname(jday)); SEE ALSO: julian_to_wkday(), setlocale(), localeconv(), ymd_to_julian(), julian_to_ymd(), julian_to_yrday(), julian_to_time(), julian_to_tm(), time_to_julian(), tm_to_julian JUL2TIME.FNC - Thu 23 Nov 89 00:20 - Page 139: NAME julian_to_time -- convert Julian date to time_t value PROTOTYPED IN: mfltime.h SYNOPSIS r = julian_to_time(julian,time); LOGICAL r; SUCCESS or ERROR if year < 1970 long julian; Julian (scalar) date time_t *time; date/time to convert DESCRIPTION This function converts scalar (Julian) dates to standard time_t date and time values. Since Julian dates do not contain time information, the time is reset to midnight. EXAMPLE long jday; time_t time; if (ERROR == julian_to_time(jday, &time)) puts("Can't convert dates prior to 1970"); SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_tm(), time_to_julian(), tm_to_julian JUL2TM.FNC - Thu 23 Nov 89 00:20 - Page 140: NAME julian_to_tm -- convert Julian date to tm structure PROTOTYPED IN: mfltime.h SYNOPSIS r = julian_to_tm(julian,t); LOGICAL r; SUCCESS or ERROR if year < 1970 long julian; Julian (scalar) date struct tm *t; date/time data to convert DESCRIPTION This function converts scalar (Julian) dates to standard date and time values in a tm structure. Since Julian dates do not contain time information, the time is reset to midnight. EXAMPLE long jday; struct tm time; if (ERROR == julian_to_time(jday, &time)) puts("Can't convert dates prior to 1970"); SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), time_to_julian(), tm_to_julian JUL2WDAY.FNC - Thu 23 Nov 89 00:20 - Page 141: NAME julian_to_wkday -- convert Julian date to day of the week PROTOTYPED IN: mfltime.h SYNOPSIS r = julian_to_wkday(julian); int r; day of week (0=Sunday, 1-Monday, etc.) long julian; Julian (scalar) date DESCRIPTION This function converts scalar (Julian) dates to a day of the week in the range of 0-6 with 0 being Sunday. EXAMPLE long jday; int i; char day[7] = {"Sun","Mon","Tue","Wed","Thu","Fri","Sat"}; i = julian_to_wkday(jday); printf("Julian date %ld was on a %s\n", jday, day[i]); SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), time_to_julian(), tm_to_julian JUL2YDAY.FNC - Thu 23 Nov 89 00:20 - Page 142: NAME julian_to_yrday -- convert Julian date to day of the year PROTOTYPED IN: mfltime.h SYNOPSIS r = julian_to_yrday(julian); unsigned r; day of the year (1 - 366) long julian; Julian (scalar) date DESCRIPTION This routine gives the day number (1-366) of a given scalar (Julian) date. EXAMPLE long jday; printf("Julian date %ld was the %drd day of the year\n", jday, julian_to_yrday(jday)); SEE ALSO: ymd_to_julian(), julian_to_ymd(), julian_to_wkday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), time_to_julian(), tm_to_julian JUL2YMD.FNC - Thu 23 Nov 89 00:20 - Page 143: NAME julian_to_ymd -- convert Julian date to year, month, date PROTOTYPED IN: mfltime.h SYNOPSIS julian_to_ymd(julian,yr,mo,day); long julian; Julian (scalar) date unsigned *yr; year unsigned *mo; month unsigned *day; date DESCRIPTION This function converts scalar (Julian) dates into calendar dates. EXAMPLE unsigned mo,day,yr; long jday; julian_to_ymd(jday, &yr, &mo, &day); printf("The calendar date is %d/%d/%d\n", mo, day, yr); SEE ALSO: ymd_to_julian(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), time_to_julian(), tm_to_julian KB_FLUSH.FNC - Thu 23 Nov 89 00:20 - Page 144: NAME KB_flush -- empties keyboard buffer DEFINED IN: mfldefs.h SYNOPSIS KB_flush(); DESCRIPTION This is one of the macros included in MFLDEFS.H. It flushes the keyboard buffer. EXAMPLES KB_flush(); KBSTATE.FNC - Thu 23 Nov 89 00:20 - Page 145: NAME _kbstate -- returns keyboard status PROTOTYPED IN: mflconio.h SYNOPSIS r = _kbstate(); int r; response DESCRIPTION This function _kbstate() returns the keyboard status flags in a strict binary format as they appear in memory, with :417 in the low byte and :418 in the high byte. EXAMPLE int r; r = _kbstate(); SEE ALSO: kbstatus(), setcaps(), clrcaps(), setnumlock(), clrnumlock() KBSTATUS.FNC - Thu 23 Nov 89 00:20 - Page 146: NAME kbstatus -- returns specified keyboard status flag PROTOTYPED IN: mflconio.h SYNOPSIS r = kbstatus(i); int r; response int i; which key status to return DESCRIPTION kbstatus(i) takes a value (fro the list below) and returns a TRUE or FALSE condition for the selected key state. For kbstatus the arguments are: 0 = return status of shift key(s) 1 = return insert state 2 = return caps lock state 3 = return num lock state 4 = return scroll lock state 5 = return <alt> state 6 = return <ctrl> state EXAMPLE setcaps(); if(kbstatus(2)) puts("Caps lock is now set"); else puts("Caps lock is NOT set"); clrcaps(); puts("Caps lock should now be off"); SEE ALSO: _kbstate(), setcaps(), clrcaps(), setnumlock(), clrnumlock() LASTCHAR.FNC - Thu 23 Nov 89 00:20 - Page 147: NAME LAST_CHAR -- returns last string character DEFINED IN: mflstrng.h SYNOPSIS r = LAST_CHAR(string); char r; last character in string char *string; string to process DESCRIPTION This is one of the macros included in MFLSTRNG.H. LAST_CHAR returns the last character of a string. EXAMPLES char *path; /* strip dangling backslash if not the root */ if ('\\' == LAST_CHAR(path) && ':' != NEXT_TO_LAST_CHAR(path)) LAST_CHAR(path) = '\0'; SEE ALSO: NEXT_TO_LAST_CHAR(), STRING_TERMINATOR() LCASFILT.FNC - Thu 23 Nov 89 00:20 - Page 148: NAME lcase_filt -- a filter to force streams to lower case PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfinstall(stream,lcase_filt); int r; SUCCESS or ERROR SFILE *stream; stream to be filtered DESCRIPTION Not a function, lcase_filt is an SFILTER structure used with sfinstall() to force streams to lower case. EXAMPLE SFILE *infile; infile = sfopen("file.ext", "r"); /* input from a file */ crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */ sfinstall(infile, lcase_filt); /* after converting to LC */ SEE ALSO: sfopen(), scopen(), sclose(), sfinstall(), crypt_install(), ucase_filt LEFT.FNC - Thu 23 Nov 89 00:20 - Page 149: NAME left -- return leftmost characters PROTOTYPED IN: mflstrng.h SYNOPSIS s = left(string,n); char *s; target string char *string; source string int n; number of characters DESCRIPTION This is an emulation of the BASIC "LEFT$" function. It returns a left-justified substring of the specified string. This function uses the stralloc() funtion to allocate memory for the returned string. This memory is maintained in a circular pool and reused. See stralloc() for further information. Use strdup() or strcpy() to save the returned string in more permanent storage. EXAMPLE char *a = "European"; a = left(a,2); puts(a); /* prints "Eu" */ SEE ALSO: right(), mid(), string_add(), str_init()), stralloc(), str_free() LOADSTR.FNC - Thu 23 Nov 89 00:20 - Page 150: NAME loadstr -- load a string with padding PROTOTYPED IN: mflstrng.h SYNOPSIS void loadstr(dest, source, qty); char *dest; string destination char *source; source string (NULL terminated) int qty; bytes to place in destination DESCRIPTION This function is similar to strcat() in that it copies a source string to a destination string. However, if the source string is smaller than "qty", the destination will be padded to the "qty" parameter with spaces. In addition, the destination string will NOT be terminated by a NULL. This is an unusual method of operation, but handy in some cases. EXAMPLE char title[] = "This is a title"; char buffer[128]; loadstr(buffer, title, 80); buffer[80] = NULL; /* add terminator */ puts(buffer); /* message will be 80 characters long, ** left justified */ LOC_CONV.FNC - Thu 23 Nov 89 00:20 - Page 151: NAME localeconv -- get master locale information PROTOTYPED IN: locale.h PORTABILITY: ANSI SYNOPSIS r = localeconv(); struct lconv *r; pointer to master locale DESCRIPTION This function returns a pointer to the master locale. See setlocale() for details. EXAMPLE struct lconv my_locale; setlocale(LC_ALL, NULL); /* returns "C" */ my_locale = localeconv(); /* copy defaults */ my_locale.TZ_txt = {"PST","PDT"};/* set Pacific Daylight Time */ my_locale.TZ_hrs=8; my_locale.DST_flag = 1; my_locale.s_time = "CA dreaming"; setlocale(LC_TIME, NULL); /* returns "CA dreaming" */ setlocale(LC_ALL, "C"); /* returns "C", resets master */ SEE ALSO: setlocale() LSQRT.FNC - Thu 23 Nov 89 00:20 - Page 152: NAME lsqrt -- extract integer square root of a long PROTOTYPED IN: mflmath.h SYNOPSIS result = lsqrt(number); long result; square root (truncated) unsigned long number; number whose square root to extract DESCRIPTION This function is part of a set of routines provided primarily for embedded systems programmers. These routines extract the square root of either a short or long integer number without the use of floating point math. EXAMPLE int i; for (i = 4; i < 9; ++i) printf("sqrt(%d) = %d\n", i, isqrt(i)); /* prints: sqrt(4) = 2 sqrt(5) = 2 sqrt(6) = 2 sqrt(7) = 2 sqrt(8) = 2 sqrt(9) = 3 */ SEE ALSO: isqrt(), isqrtr(), lsqrtr() LSQRTR.FNC - Thu 23 Nov 89 00:20 - Page 153: NAME lsqrtr -- extract integer square root of a long w/ rounding PROTOTYPED IN: mflmath.h SYNOPSIS result = lsqrtr(number); long result; square root (rounded) unsigned long number; number whose square root to extract DESCRIPTION This function is part of a set of routines provided primarily for embedded systems programmers using. lsqrtr() extracts the integer square root of a long w/ rounding. EXAMPLE int i; for (i = 4; i < 9; ++i) printf("sqrt(%d) = %d\n", i, isqrtr(i)); /* prints: sqrt(4) = 2 sqrt(5) = 2 sqrt(6) = 2 sqrt(7) = 3 sqrt(8) = 3 sqrt(9) = 3 */ SEE ALSO: isqrt(), isqrtr(), lsqrt() LV1WS.FNC - Thu 23 Nov 89 00:20 - Page 154: NAME lv1ws -- remove excess whitespace from string PROTOTYPED IN: mflstrng.h SYNOPSIS void lv1ws(str); char *str; string to modify DESCRIPTION This function modifies the specified string in place. White space is defined as the space character, tab character, vertical tab, linefeed, carriage return, and formfeed. Each white space character is replaced with a space. Multiple white space characters are replaced by a single space. EXAMPLE char string[] = " This is a \x8\x0c string \n"; lv1ws(string); /* returns " This is a string \n" */ SEE ALSO: rmlead(), rmtrail(), rmallws() MID.FNC - Thu 23 Nov 89 00:20 - Page 155: NAME mid -- return embedded substring PROTOTYPED IN: mflstrng.h SYNOPSIS s = mid(string,n,m); char *s; target string char *string; source string int n; first character int m; number of characters DESCRIPTION This is an emulation of the BASIC "MID$" function. It returns a specified-length substring of the specified string. This function uses the stralloc() funtion to allocate memory for the returned string. This memory is maintained in a circular pool and reused. See stralloc() for further information. Use strdup() or strcpy() to save the returned string in more permanent storage. EXAMPLE char *a; char *c = "Skaters"; a = mid(c,2,2); puts(a); /* prints "ka" */ SEE ALSO: left(), right(), string_add(), str_init(), stralloc(), str_free() MKBOX.FNC - Thu 23 Nov 89 00:20 - Page 156: NAME mkbox -- make a box on the screen PROTOTYPED IN: mflconio.h SYNOPSIS #include <mflconio.h> void mkbox(startr, startc, width, ht, page); int startr; starting row (top) int startc; starting column (left) int width; how many columns wide int ht; how many rows high int page; which video page (assuming proper video mode) DESCRIPTION This function will make a double line box using the IBM graphics characters on the "page" specified. The "startr" and "startc" parameters anchor the upper left corner. The "ht" and "width" set the dimensions. No checks are made for valid numbers. Function can be used with both CGA and Mono cards, and with EGA cards in CGA or MONO modes. EXAMPLE mkbox(0, 0, 80, 23, 0); /* will make a box around the outside of an 80 x 24 screen. */ SEE ALSO: disp_box() MKTONE.FNC - Thu 23 Nov 89 00:20 - Page 157: NAME mktone -- make a tone to the speaker PROTOTYPED IN: mflsound.h SYNOPSIS #include "sound.h" void mktone(freq, update, delay); int freq; frequency of tone int update speaker control command int delay value to delay before returning DESCRIPTION This is a very simple function to make a tone on the IBM speaker using the standard timer controller. The frequency is an integer which increases the pitch of the tone with decreasing values. the delay is an integer which is used in a very simple "for" loop to control duration of the tone. A value of 0 is no delay. The update integer is defined in sound.h as follows: if update == UPDATE just send frequency and delay if update == TOGGLE turn sound off after delay is complete else turn sound on and leave it on when returning Any tone may be turned off by setting freq to 0. In this case, update and delay values are ignored and may be set to any value. EXAMPLE #include <mflsound.h> mktone(1000, TOGGLE, 1000); /* make a short beep */ mktone(1000, ON, 0); /* turn a tone on */ mktone(0, 0, 0); /* turn a tone off */ mktone(2000, ON, 0); /* turn a tone on */ mktone(1000, UPDATE, 0); /* raise the pitch */ mktone(0, 0, 0); /* turn it off */ SEE ALSO: soundon(), soundoff() MONTHIS.FNC - Thu 23 Nov 89 00:20 - Page 158: NAME monthis -- return a string pointer to name of month PROTOTYPED IN: mfltime.h SYNOPSIS char *monthis(month); int month; number of month 0-11 DESCRIPTION This function returns a pointer to a character string naming the specified month. The string is null terminated and may be used directly or copied to another string. Month 0 is January. EXAMPLE printf("This is %s", monthis(7)); /* printout will be: This is August */ MSECPAWS.FNC - Thu 23 Nov 89 00:20 - Page 159: NAME msec_pause -- pause a given number of milliseconds PROTOTYPED IN: mfltime.h SYNOPSIS msec_pause(msec) long msec; number of milliseconds to pause DESCRIPTION This function is part of a group of high-precision timing functions with an accuracy of one microsecond on IBM and closely compatible computers. To function properly, these functions require the host system to use either an 8253 or 8254 counter/timer chip based at I/O address 40h to generate the 18.2 Hz system interrupt used by DOS. These functions further assume that DOS uses the four bytes at 40:6C for its timekeeping function. These have proven to be safe assumptions for all IBM PC's and PS/2's, Compaq's, as well as most other clone computers and single-board computers designed for MS/PC-DOS compatibility. The sole exception is msec_pause() which requires the counter/timer chip but makes no other assumptions. msec_pause() is a delay function which delays a specified number of milliseconds. EXAMPLE long r; msec_pause(r); SEE ALSO: usec_clock(), restart_uclock(), usec_delay(), usec_difftime(), usec_timeout(), msec_pause() NEWEXT.FNC - Thu 23 Nov 89 00:20 - Page 160: NAME newext -- change a filename extension PROTOTYPED IN: mflfiles.h SYNOPSIS void newext(old, new, extn); char *old original filename string char *new destination for new filename char *extn new extension string DESCRIPTION This function will make a new filename from an existing filename and a specified extension string. The original filename string is left unchanged, since its base is copied to a new string area. Nothing is returned. EXAMPLE char old[] = "FOOBAR.COM"; char new[14]; newext(old, new, "BIN"); After operation, the filename string in "new" will be: FOOBAR.BIN Character strings are NULL terminated. The original string need not have any extension or period terminator, and may contain a path specifier. Note that the destination string area must be long enough to hold the new filename. SEE ALSO: exttyp(), badext() NXT2LAST.FNC - Thu 23 Nov 89 00:20 - Page 161: NAME NEXT_TO_LAST_CHAR -- returns penultimate string character DEFINED IN: mflstrng.h SYNOPSIS r = NEXT_TO_LAST_CHAR(string); char r; penultimate character in string char *string; string to process DESCRIPTION This is one of the macros included in MFLSTRNG.H. It returns the next to last character (the last character before the NULL) in a character string. EXAMPLES char *path; /* strip dangling backslash if not the root */ if ('\\' == LAST_CHAR(path) && ':' != NEXT_TO_LAST_CHAR(path)) LAST_CHAR(path) = '\0'; SEE ALSO: LAST_CHAR(), STRING_TERMINATOR() This function is found in SMZTx.LIB for the Zortech Compiler OFFSETOF.FNC - Thu 23 Nov 89 00:20 - Page 162: NAME offsetof -- returns element's position in struct DEFINED IN: mfldefs.h PORTABILITY: offsetof() is compatible with ANSI C and is implemented as a macro per the draft ANSI specification. SYNOPSIS r = offsetof(st,el); int r; offset within... struct st; structure of... void el; structure element DESCRIPTION The offsetof() macro is defined in the draft ANSI standard as returning the offset of an element within a structure. EXAMPLES struct xyz { long abc; int def; }; printf("def is at position %d\n", offsetof(xyz,def)); /* prints "4" */ OPEND.FNC - Thu 23 Nov 89 00:20 - Page 163: NAME openp -- open a file in the PATH PROTOTYPED IN: mflfiles.h SYNOPSIS fh = opend(name, mode, envar); int fh; file handle returned char *name; filename int mode; mode char *envar name of environment variable DESCRIPTION This function allows the opening of a file in other than just the current directory. It attempt the open in the current directory first, and if that fails, will then expand to search along the PATH environment variable. It will return -1 upon failure. The file MUST EXIST in order for a file handle to be returned. Therefore, this function cannot be used to create new files. See fopenp for the same function using file descriptor structures. EXAMPLE int fh; if((fh = opend("stdio.h", O_READ, "INCLUDE")) == -1) cant("stdio.h"); else puts("stdio.h is open for reading"); SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng() OPENDIR.FNC - Thu 23 Nov 89 00:20 - Page 164: NAME opendir -- open a directory for reading PROTOTYPED IN: mflfiles.h SYNOPSIS r=opendir(s1); DOS_DIR *r; directory file pointer. r->dd_size - number of directory entries r->dd_loc - current entry number char *s1; name of directory to open DESCRIPTION This function is similar to one found on Unix 4.2 BSD systems. IT is designed to make reading DOS directories almost as simple as reading normal files. The opendir() function is an analog of fopen(). It returns a special type of file pointer upon success or a NULL in case of error. Possible errors include trying to open a non-directory or exceeding the maximum number of permissible open files. Like DOS files, there is a limit to how many directories may be open at one time. Under the small and medium models, only 16 directories may be opened at one time. Under the large and compact models, up to 48 directories may be open simultaneously. When the directory is opened, the dd_size field in the DOS_DIR structure is filled in with the total number of files, including subdirectories and "dot" directories contained. The opendir() function sets the DFerr global variable depending on their return status. The error codes in ERROR.H are used along with EOF and SUCCESS. EXAMPLE char *name[] = "C:\looney\bin"; DOS_DIR *dirp; struct FIND *ffblk; if(dirp=opendir(name)) { printf("%s contains %d entries\n", name, dirp->dd_size); while (ffblk=readdir(dirp)) { printf("%3d - %s\n", dirp->dd_loc, ffblk->name); } closedir(dirp); } SEE ALSO readdir(), closedir() OPENG.FNC - Thu 23 Nov 89 00:20 - Page 165: NAME openg -- opend/openp combination PROTOTYPED IN: mflfiles.h SYNOPSIS int fh; file handle returned char *name; filename int mode; mode char *envar; name of environment variable DESCRIPTION This function allows the opening of a file in other than just the current directory. It will attempt the open in the current directory first, and if that fails, will then expand to search along a path specified by an environment variable. If this fails it will continue searching along the PATH variable This function will return -1 upon failure. The file MUST EXIST in order for a file handle to be returned. Therefore, fopeng() cannot be used to create new files. See fopeng for the same functions using file descriptor structures. EXAMPLE int fh; if((fh = openg("stdio.h", O_READ, "INCLUDE")) == -1) cant("stdio.h"); else puts("stdio.h is open for reading"); SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng() OPENP.FNC - Thu 23 Nov 89 00:20 - Page 166: NAME openp -- open a file in the PATH PROTOTYPED IN: mflfiles.h SYNOPSIS fh = openp(name, mode); int fh; file handle returned char *name; filename int mode; mode DESCRIPTION This function allows the opening of a file in other than just the current directory. It will attempt the open in the current directory first, and if that fails, will then expand to search along a path specified by an environment variable. openp() will return -1 upon failure. The file MUST EXIST in order for a file handle to be returned. Therefore, this function cannot be used to create new files. See fopenp for the same functions using file descriptor structures. EXAMPLE int fh; if((fh = openp("foo.bar", O_READ)) == -1) cant("foo.bar"); else puts("File is now opened!"); SEE ALSO: opend(), openg(), fopend(), fopenp(), fopeng() POPDIR.FNC - Thu 23 Nov 89 00:20 - Page 167: NAME popdir -- return to previous directory PROTOTYPED IN: mflfiles.h SYNOPSIS r = popdir(); int r; returns: -1 if stack empty 0 if error 1 if success (same drive) 2 if success (changed drives) DESCRIPTION This functions restores the last disk directory stored with pushdir. A static stack of eight directories is maintained for small and medium memory models, thirty-two for large and compact models. EXAMPLE if (0 < pushdir("c:utility")) { /* do some stuff in C:UTILITY */ if (0 < popdir()) puts("We're back home!"); else puts("oops..."); } else puts("Couldn't change to C:UTILITY"); SEE ALSO: pushdir() PR_CARRE.FNC - Thu 23 Nov 89 00:20 - Page 168: NAME pr_carret -- send a carriage return to the printer PROTOTYPED IN: mflsys.h SYNOPSIS void pr_carret(); DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_carret(); SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_set(), pr_putc() PR_EJECT.FNC - Thu 23 Nov 89 00:20 - Page 169: NAME pr_eject -- send a formfeed to the printer PROTOTYPED IN: mflsys.h SYNOPSIS void pr_eject(); DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_putline("Hello World"); pr_eject(); SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_carret(), pr_set(), pr_putc() PR_NL.FNC - Thu 23 Nov 89 00:20 - Page 170: NAME pr_nl -- print a carriage return/line feed to printer PROTOTYPED IN: mflsys.h SYNOPSIS void pr_nl(); DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_putline("Hello World"); pr_eject(); SEE ALSO: pr_puts(), pr_putline(), pr_eject(), pr_carret(), pr_set(), pr_putc() PR_PUTC.FNC - Thu 23 Nov 89 00:20 - Page 171: NAME pr_putc -- send a character to the printer PROTOTYPED IN: mflsys.h SYNOPSIS r = pr_putc(ch); char ch; int r; (returned status) DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE int r; pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ r = pr_putc('Y'); pr_eject(); SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_carret(), pr_set() PR_PUTLN.FNC - Thu 23 Nov 89 00:20 - Page 172: NAME pr_putline -- print a string, and a cr/lf to the printer PROTOTYPED IN: mflsys.h SYNOPSIS pr_putline(str); char *str; DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_putline("Hello World"); pr_eject(); SEE ALSO: pr_nl(), pr_puts(), pr_eject(), pr_carret(), pr_set(), pr_putc() PR_PUTS.FNC - Thu 23 Nov 89 00:20 - Page 173: NAME pr_puts -- print a string to the printer PROTOTYPED IN: mflsys.h SYNOPSIS pr_puts(str); char *str; DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_puts("Hello World"); SEE ALSO: pr_nl(), pr_putline(), pr_eject(), pr_carret(), pr_set(), pr_putc() PR_SET.FNC - Thu 23 Nov 89 00:20 - Page 174: NAME pr_set -- set the number of the current printer PROTOTYPED IN: mflsys.h SYNOPSIS pr_set(num); int num 0, 1, or 2 DESCRIPTION This is part of a series of routines use the low level functions blpr() and blprstat() to access the LPT? ROM-BIOS drivers directly. pr_putc() returns the same status that is returned by blprstat(). Be sure to use pr_set() to set which LPT is to be accessed. Note that the library defaults to LPT1:, and pr_set() may be ignored if that printer is to be used. EXAMPLE pr_set(LP1); /* LP1, LP2, LP3 defined in smdefs.h */ pr_putline("Hello World"); pr_eject(); SEE ALSO: pr_nl(), pr_puts(), pr_line(), pr_eject(), pr_carret(), pr_putc() PRTSC.FNC - Thu 23 Nov 89 00:20 - Page 175: NAME PrtSc -- prints the current text screen PROTOTYPED IN: mflsys.h SYNOPSIS r = PrtSc(); int r; SUCCESS or ERROR if printing was already in process DESCRIPTION The PrtSc() function works identically to the keyboard key of the same name - it prints the contents of the current text screen. Note that the results when displaying graphics are undefined. EXAMPLE if (0 == getPrtSc_stat()) /* make sure not already printing */ PrtSc(); SEE ALSO: getPrtSc_stat() PUSHDIR.FNC - Thu 23 Nov 89 00:20 - Page 176: NAME pushdir -- save current directory, then go to a new one PROTOTYPED IN: mflfiles.h SYNOPSIS r = pushdir(newdir); int r; returns: -1 if stack full 0 if error 1 if success (same drive) 2 if success (changed drives) char *newdir; directory (drive and path) to move to DESCRIPTION This function saves the current disk directories prior to moving around the disk system. A static stack of eight directories is maintained for small and medium memory models, thirty-two for large and compact models. EXAMPLE if (0 < pushdir("c:utility")) { /* do some stuff in C:UTILITY */ if (0 < popdir()) puts("We're back home!"); else puts("oops..."); } else puts("Couldn't change to C:UTILITY"); SEE ALSO: popdir RDY_RCV.FNC - Thu 23 Nov 89 00:20 - Page 177: NAME ready_rcv -- check for character availability PROTOTYPED IN: mflsys.h SYNOPSIS x = ready_rcv(port); DESCRIPTION ready_rcv() is part of a set of very low level (direct port access) subroutines to enable I/O through COM1 through COM4. Only setport() uses BIOS int 14H. These functions are not intended to be the ultimate in async functions, but a starting point for an integrated set of async functions, and a means of getting at the serial port directly for speed and to work around the problems that some "clone" BIOS routines have in returning proper status values. File "smdefs.h" contains #defines to handle these ports mnemonically. ready_rcv() returns a TRUE condition if a character is waiting to be read, but no error conditions are returned. If the program "loop" is short and fast enough, these functions will be ample to allow communications at up to 9600 baud. A program has already been implemented to communicate with a prom programmer at this rate, so it can be done. However, when the program does not poll the receiver fast enough it is likely that characters may be lost and the maximum usable baud rate will be lower. It is highly unlikely that baud rates less than 2400 baud will be necessary if the program is properly structured. EXAMPLE /* this routine receives characters from COM1 at one ** speed and resends them to COM2 at another speed */ unsigned char i; setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity, ** 8-bits, 1 stop bit */ setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */ while(TRUE) { if(!ready_rcv(SER1)) continue; /* wait for a char */ i = readchar(SER1); /* fetch it */ while(!ready_xmt(SER2));/* wait for xmtr to be ready */ writechar(SER2, i); /* then send it */ } SEE ALSO: readchar(), ready_xmt(), setport(), writechar() RDY_XMT.FNC - Thu 23 Nov 89 00:20 - Page 178: NAME ready_xmt -- check if port can accept a char to send PROTOTYPED IN: mflsys.h SYNOPSIS x = ready_xmt(port); int port; port number int x; TRUE if condition exists, else FALSE (0) DESCRIPTION ready_xmt() is part of a set of very low level (direct port access) subroutines to enable I/O through COM1 through COM4. Only setport() uses BIOS int 14H. These functions are not intended to be the ultimate in async functions, but a starting point for an integrated set of async functions, and a means of getting at the serial port directly for speed and to work around the problems that some "clone" BIOS routines have in returning proper status values. File "smdefs.h" contains #defines to handle these ports mnemonically. ready_xmt() returns a TRUE condition if the transmit holding register is empty; i.e., the transmitter can accept a character to send. In both these functions, the status returned is a result of reading the port status and masking all but the relevant bit. These routines will NOT return errors such as overrun or parity. If the program "loop" is short and fast enough, these functions will be ample to allow communications at up to 9600 baud. A program has already been implemented to communicate with a prom programmer at this rate, so it can be done. However, when the program does not poll the receiver fast enough it is likely that characters may be lost and the maximum usable baud rate will be lower. It is highly unlikely that baud rates less than 2400 baud will be necessary if the program is properly structured. RDY_XMT.FNC - Thu 23 Nov 89 00:20 - Page 179: EXAMPLE /* this routine receives characters from COM1 at one ** speed and resends them to COM2 at another speed */ unsigned char i; setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity, ** 8-bits, 1 stop bit */ setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */ while(TRUE) { if(!ready_rcv(SER1)) continue; /* wait for a char */ i = readchar(SER1); /* fetch it */ while(!ready_xmt(SER2));/* wait for xmtr to be ready */ writechar(SER2, i); /* then send it */ } SEE ALSO: readchar(), ready_rcv(), setport(), writechar() READCHAR.FNC - Thu 23 Nov 89 00:20 - Page 180: NAME readchar -- read a character from serial port PROTOTYPED IN: mflsys.h SYNOPSIS r = readchar(port); unsigned char r; character to send or receive int port; port number DESCRIPTION readchar() is part of a set of very low level (direct port access) subroutines to enable I/O through COM1 through COM4. Only setport() uses BIOS int 14H. These functions are not intended to be the ultimate in async functions, but a starting point for an integrated set of async functions, and a means of getting at the serial port directly for speed and to work around the problems that some "clone" BIOS routines have in returning proper status values. File "smdefs.h" contains #defines to handle these ports mnemonically. readchar() will return the character waiting in the receiver register of the port. It is returned as an unsigned char to facilitate 8-bit binary transfer protocols. If the program "loop" is short and fast enough, these functions will be ample to allow communications at up to 9600 baud. A program has already been implemented to communicate with a prom programmer at this rate, so it can be done. However, when the program does not poll the receiver fast enough it is likely that characters may be lost and the maximum usable baud rate will be lower. It is highly unlikely that baud rates less than 2400 baud will be necessary if the program is properly structured. READCHAR.FNC - Thu 23 Nov 89 00:20 - Page 181: EXAMPLE /* this routine receives characters from COM1 at one ** speed and resends them to COM2 at another speed */ unsigned char i; setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity, ** 8-bits, 1 stop bit */ setport(SER2, 0xc3); /* set COM2 the same, but 4800 bps */ while(TRUE) { if(!ready_rcv(SER1)) continue; /* wait for a char */ i = readchar(SER1); /* fetch it */ while(!ready_xmt(SER2));/* wait for xmtr to be ready */ writechar(SER2, i); /* then send it */ } SEE ALSO: ready_xmt(), ready_rcv(), setport(), writechar() READDIR.FNC - Thu 23 Nov 89 00:20 - Page 182: NAME readdir -- read directory entries PROTOTYPED IN: mflfiles.h SYNOPSIS r=readdir(d1); struct FIND *r; information about this directory entry DOS_DIR *d1; directory file pointer DESCRIPTION This function is part of a group of functions designed to make reading DOS directories almost as simple as reading normal files. The readdir() function reads sequential entries from the open directory whose file pointer is passed, much as fgets() reads sequential lines of text from a normal file. The dd_loc element in the DOS_DIR structure is updated as each is read. After the last directory entry is read (i.e. dd_loc == dd_size), subsequent calls to readdir() will return NULL. Entries are read in normal find_t structures as used by the other _dos_findfirst/next routines. The readdir() function sets the DFerr global variable depending on their return status. The error codes in ERROR.H are used along with EOF and SUCCESS. EXAMPLE char *name[] = "C:\looney\bin"; DOS_DIR *dirp; struct find_t *ffblk; if(dirp=opendir(name)) { printf("%s contains %d entries\n", name, dirp->dd_size); while (ffblk=readdir(dirp)) { printf("%3d - %s\n", dirp->dd_loc, ffblk->name); } closedir(dirp); } SEE ALSO: opendir(), closedir() REBOOT.FNC - Thu 23 Nov 89 00:20 - Page 183: NAME reboot -- force a warm or cold reboot PROTOTYPED IN: mflsys.h SYNOPSIS void reboot(t); int t; type of reboot, WARM or COLD (see MFLSYS.H) DESCRIPTION The reboot() function does just what it says - forces a warm (Ctrl-Alt- Del style) or cold (big red switch style) reboot. EXAMPLE if (disaster == minor) reboot(WARM); else reboot(COLD); REPCHAR.FNC - Thu 23 Nov 89 00:20 - Page 184: NAME repchar -- repeat a character n times to fd PROTOTYPED IN: mflstrng.h SYNOPSIS void repchar(chr, qty, fd); char chr; character to send int qty; number of characters to send FILE *fd; file descriptor of output channel DESCRIPTION This function sends qty number of chr to fd, which is usually stdout, stderr, or an open file. Maximum qty is 128. If qty > 128, it will be truncated to 128. This limit is due to an internal string buffer. For speed, the string is filled and then fputs() is called to output the data as a string. EXAMPLE repchar('X', 50, stdout); /* to output a double horizontal line: */ #include <mflconio.h> repchar(DHLINE, 50, stdout); RIGHT.FNC - Thu 23 Nov 89 00:20 - Page 185: NAME right -- return rightmost characters PROTOTYPED IN: mflstrng.h SYNOPSIS s = right(string,n); char *s; target string char *string; source string int n; number of characters DESCRIPTION This is an emulation of the BASIC "RIGHT$" function. It returns a right-justified substring of the specified string. This function uses the stralloc() funtion to allocate memory for the returned string. This memory is maintained in a circular pool and reused. See stralloc() for further information. Use strdup() or strcpy() to save the returned string in more permanent storage. EXAMPLE char *a; char *b = "Hardware"; a = right(b,2); puts(a); /* prints "re" */ SEE ALSO: left(), mid(), string_add(), str_init(), stralloc(), str_free() RINDEX.FNC - Thu 23 Nov 89 00:20 - Page 186: NAME rindex -- offset of rightmost char in a string DEFINED IN: mflstrng.h SYNOPSIS r = rindex(s,c); int r; offset (index) of rightmost occurance of char c in string s, -1 if unsuccessful char *s; string to search char c; character for which to search DESCRIPTION This is one of the macros included in MFLSTRNG.H. Note that rindex() is available as a function in many systems and may return an integer offset, as done here, or may simply be aliases for strchr() and chrrchr(), respectively. It is provided here to aid portability, but may need to be modified or undefined depending on the original implementation. EXAMPLES int offset; offset=rindex("ABCDEDCBA", 'C'); /* returns 6 */ SEE ALSO: index() RMALLWS.FNC - Thu 23 Nov 89 00:20 - Page 187: NAME rmallws -- remove all whitespace from string PROTOTYPED IN: mflstrng.h SYNOPSIS str=rmallws(str); char *str; string to modify DESCRIPTION This string function modifys the specified string in place. White space is defined as the space character, tab character, vertical tab, linefeed, carriage return, and formfeed. String size is limited to 255 characters, although the source code can be modified to increase or decrease that. If the string exceeds that size, it is truncated. Note that all strings are modified "in place" and all functions return a pointer to the modified string. EXAMPLE char string[] = " This is a string \n"; rmallws(string); /* returns "Thisisastring" */ SEE ALSO: rmlead(), rmtrail(), lv1ws() RMLEAD.FNC - Thu 23 Nov 89 00:20 - Page 188: NAME rmlead -- remove leading whitespace from string PROTOTYPED IN: mflstrng.h SYNOPSIS str=rmlead(str); char *str; string to modify DESCRIPTION This string function will modify the specified string in place. White space is defined as the space character, tab character, vertical tab, linefeed, carriage return, and formfeed. String size is limited to 255 characters, although the source code can be modified to increase or decrease that. If the string exceeds that size, it is truncated. Note that all strings are modified "in place" and all functions return a pointer to the modified string. EXAMPLE char string[] = " This is a string \n"; rmlead(string); /* returns "This is a string \n" */ SEE ALSO rmallws(), rmtrail(), lv1ws() RMTICK.FNC - Thu 23 Nov 89 00:20 - Page 189: NAME removetick -- remove a timer interrupt service routine PROTOTYPED IN: mfltime.h SYNOPSIS void removetick(); DESCRIPTION "ticker" is not actually a C function, but a routine which is installed on interrupt 1CH. At each interrupt (18.21 times per second) this routine decrements an integer (16 bits) whose address was passed during installation. The C program can load and test this integer at any time to perform time-based operations. When the variable is decremented to zero, it is not decremented any further; i.e., no underflow occurs. Therefore, the integer is actually an unsigned integer with a maximum count of 65535, or (65535/18.2) seconds. installtick() installs the ticker on interrupt 1CH and saves the address of the passed variable. removetick() restores the interrupt 1CH vector to its original state. Any other routines already installed on this vector are executed after ticker, since the ticker chains to the original vector after execution. EXAMPLE int counter; main() { installtick(&counter); counter = 18 * 10; /* about 10 seconds */ while(counter > 0); /* delay here */ removetick(); } CAVEAT It is imperative to call removetick() BEFORE terminating the program, Otherwise, the system will crash! SEE ALSO: ctlbrk(), criterr(), installtick() RMTRAIL.FNC - Thu 23 Nov 89 00:20 - Page 190: NAME rmtrail -- remove trailing whitespace from string PROTOTYPED IN: mflstrng.h SYNOPSIS str=rmtrail(str); char *str; string to modify DESCRIPTION This string function will modify the specified string in place. White space is defined as the space character, tab character, vertical tab, linefeed, carriage return, and formfeed. String size is limited to 255 characters, although the source code can be modified to increase or decrease that. If the string exceeds that size, it is truncated. Note that all strings are modified "in place" and all functions return a pointer to the modified string. EXAMPLE char string[] = " This is a string \n"; rmtail(string); /* returns " This is a string" */ SEE ALSO: rmallws(), rmlead(), lv1ws() RSTUCLK.FNC - Thu 23 Nov 89 00:20 - Page 191: NAME restart_uclock -- re-initialize the microsecond clock PROTOTYPED IN: mfltime.h SYNOPSIS restart_uclock(); DESCRIPTION This is part of a group of functions that implement timing functions with an accuracy of one microsecond on IBM and closely compatible computers. To function properly, these functions require the host system to use either an 8253 or 8254 counter/timer chip based at I/O address 40h to generate the 18.2 Hz system interrupt used by DOS. These functions further assume that DOS uses the four bytes at 40:6C for its timekeeping function. These have proven to be safe assumptions for all IBM PC's and PS/2's, Compaq's, as well as most other clone computers and single-board computers designed for MS/PC-DOS compatibility. The sole exception is msec_pause() which requires the counter/timer chip but makes no other assumptions. The usec_clock() function relies on data which rolls over at midnight each day and can handle this. However, if a program is to run continuously for many days, it becomes necessary to take action to prevent internal overflow. This may be done by resetting the internal registers used by usec_clock() at least once per day by calling restart_uclock(). EXAMPLE restart_uclock(); SEE ALSO: usec_clock(), restart_uclock(), usec_delay(), usec_difftime(), usec_timeout(), msec_pause() SCLOSE.FNC - Thu 23 Nov 89 00:20 - Page 192: NAME sclose -- close a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sclose(stream); int r; SUCCESS or ERROR SFILE *stream; stream to close DESCRIPTION The sclose() function is used to close streams opened with either the sfopen() or scopen() functions. EXAMPLE int serial_out(); SFILE *infile, *outfile; infile = sfopen("file.ext", "r"); /* input from a file */ outfile = scopen(serial_out, "w"); /* output to serial I/O */ ... if (SUCCESS != sclose(infile)) puts("couldn't close file.ext"); if (SUCCESS != sclose(outfile)) puts("couldn't close serial I/O"); SEE ALSO: sfopen(), scopen() SCOPEN.FNC - Thu 23 Nov 89 00:20 - Page 193: NAME scopen -- open a channel stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = scopen(gfunc,ufinc,mode); SFILE *r; pointer to an SFILE record - equivalent to fopen's FILE pointer - NULL in case of error int (*gfunc)(); function to call when reading (mode includes "r") or writing (mode includes "w") streams int (*ufunc)(); function to call when "ungetting" (mode includes "r" only) characters previously read from streams char *mode; mode in which to open the streeam DESCRIPTION The scopen() function is used to open streams to channels. Comparable to sfopen(), scopen() is a general-purpose function to allow user-defined functions to interface with the rest of the MicroFirm Function Library's stream I/O package. EXAMPLE int is_char_rdy(), get_serial(); /* from some serial comms */ SFILE *infile, *outfile; char buf[128]; int s_in(void) { while (!is_char_rdy()) ; return get_serial(); } int s_unget(int ch) { return serial_unget(ch); } infile = scopen(s_in,s_unget,"r"); /* input from serial I/O */ outfile = sfopen("file.ext", "w"); /* output to a file */ sfinstall(infile, ucase_filt); /* convert input to U.C. */ crypt_install(outfile, "mykey", 0); /* encrypt output stream */ sfgets(buf, 128, infile); /* read a string */ sfputs(buf, outfile); /* write it out */ SEE ALSO: sfopen(), sclose() SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 194: NAME setlocale -- set country-specific information PROTOTYPED IN: locale.h PORTABILITY: ANSI SYNOPSIS r = setlocale(category,locale); char *r; current locale spec int category; type of locale info to be set char *locale; locale specification DESCRIPTION The setlocale() function specified in the ANSI draft. Although all categories are currently recognized, not all are supported. As defined by ANSI and in LOCALE.H, the lconv structure may be envisioned as a concatenation of several sub-structures containing information which will vary depending on locale. The valid categories are defined by `LC_' macros as follows: LC_ALL This sets the entire lconv structure including all sub-categories. LC_COLLATE Not supported, this is designed to vary the action of the string comparison functions. LC_CTYPE Not supported, this designed to affect the action of functions defined in CTYPE.H. LC_MONETARY This contains formatting information for expressing monetary values (see below). LC_NUMERIC This contains formatting information for expressing arithmetic values (see below). LC_TIME This contains formatting information used by strftime() and julian_to_dayname() (see below). To set an active locale, setlocale() is called with the category of locale to set and the name of the locale to set. If the name of the locale passed is NULL, the name of the currently active locale is returned. If the name of the locale passed is empty (""), the default locale is set (see below). Calling setlocale() returns the locale name of the locale which was set. Currently specified locales include: "C" ANSI-mandated minimum locale, suitable for minimum-functionality usage in English-speaking countries. "USA" The default (empty locale name string) locale. SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 195: To set a new or non-English locale, you must first add a structure of type lconv to the _lconv[] array in LOCALE.C, setting each of its category names (fields beginning with "s_") to the name of your new locale. This structure elements are as follows: char *s_all Name of the locale returned by LC_ALL char *s_collate Name of the locale returned by LC_COLLATE char *s_ctype Name of the locale returned by LC_CTYPE char *s_monetary Name of the locale returned by LC_MONETARY char *currency_symbol String containing the locale's currency symbol, e.g. "$" in the U.S. char *int_curr_symbol String containing the locale's international currency symbol, e.g. "USD" in the U.S. char *mon_decimal_point String containing the locale's decimal point, e.g. "." in the U.S. char *mon_thousands_sep String containing the locale's thousands separator, e.g. "," in the U.S. char *mon_grouping Although this is a string, only the first character's ASCII value is used to determine the size of character groupings in specifying monetary values, i.e. for the U.S. use "\3" to specify 3-character groupings. char *positive_sign String containing the positive symbol, e.g. "+" in the U.S. char *negative_sign String containing the negative symbol, e.g. "-" in the U.S. char int_frac_digits The number of digits to display for fractional international monetary quantities, e.g. 2 for the U.S. char frac_digits The number of digits to display for fractional monetary quantities, e.g. 2 for the U.S. char p_cs_precedes Whether the currency symbol precedes (1) or follows (0) the value for positive monetary values. char n_cs_precedes Whether the currency symbol precedes (1) or follows (0) the value for negative monetary values. char p_sep_by_space Whether the currency symbol is separated by a space (1) or not (0) for positive monetary values. char n_sep_by_space Whether the currency symbol is separated by a space (1) or not (0) for negative monetary values. char p_sign_posn Whether, for positive monetary values: (0) parentheses surround the value and the currency symbol, (1) the positive sign precedes the value and the currency symbol, (2) the positive sign follows the value and the currency symbol, (3) the positive sign immediately precedes the currency symbol, or SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 196: (4) the positive sign immediately follows the currency symbol. char n_sign_posn Whether, for negative monetary values: (0) parentheses surround the value and the currency symbol, (1) the negative sign precedes the value and the currency symbol, (2) the negative sign follows the value and the currency symbol, (3) the negative sign immediately precedes the currency symbol, or (4) the negative sign immediately follows the currency symbol. char *s_numeric Name of the locale returned by LC_NUMERIC char *decimal_point String containing the locale's decimal point, e.g. "." in the U.S. char *thousands_sep String containing the locale's thousands separator, e.g. "," in the U.S. char *grouping Although this is a string, only the first character's ASCII value is used to determine the size of character groupings in specifying arithmetic values, i.e. for the U.S. use "\3" to specify 3-character groupings. char *s_time Name of the locale returned by LC_TIME char *day[7][2] An array of weekday names, starting with Sunday, and their abbreviations. char *month[12][2] An array of month names, starting with January, and their abbreviations. int TZ_secs Seconds to add to GMT to get local standard time. int DST_flag 0 if local standard time, 1 if local daylight time. char *TZ_txt[2] The local time zone names, both normal ([0]) and daylight ([1]). Defaults to "CST", "CDT". char tim_sep Character used to separate time fields (':'). char *p_FMTA Morning AM/PM indicator ("AM"). char *p_FMTP Evening AM/PM indicator ("PM"). char *c_FORMAT strftime() format string for standard display. See STRFTIME.C for exact usage. char *x_FORMAT strftime() format string for date display. char *X_FORMAT strftime() format string for time display. char fmt_24 Indicates formatting of hours between midnight and 1:00 AM. Zero indicates to display as 00:mm:ss, non-zero indicates to use 24:mm:ss. SET_LOC.FNC - Thu 23 Nov 89 00:20 - Page 197: LOCALE.C maintains a master locale for use by applications programs. This allows different locale categories to be mixed in the master locale. For example, the "USA" locale may be specified for monetary value formatting while the default "C" locale might be used for numeric values, thus avoiding the grouping and thousands separators in the LC_NUMERIC category of the "USA" locale. To access the master locale, the function localeconv() is called which returns a pointer to the master locale. The strftime() function uses an additional feature of setlocale(), the ability to use environment variables. Two environment variables are used, "TIMEZONE" and "DAYLIGHT". The TIMEZONE variable takes the form "NNN[+/-]TT[TTTT]DDD" where "NNN" is the name for the normal time zone, "DDD" is the name when using daylight savings time, and "TT[TTTT]" is the local offset from GMT in either hours (range: -24 to 24) or seconds. For example to set Pacific Time, use: "SET TIMEZONE=PST8" sets PST "SET TIMEZONE=PST9PDT" sets PDT The DAYLIGHT variable is set to either "0" or a non-zero numeric value to indicate whether daylight savings time is in effect. For example, if TIMEZONE were set as above for PDT, the use of PST could be forced by: "SET DAYLIGHT=0" NOTES: When using the "USA" locale, "TZ_hrs" and "DST_flag" are set to default values of 6 and 0, respectively, corresponding to CST. When using the default "C" locale, "TZ_secs" and "DST_flag" are set to default values of 0 and 0, respectively. When using strftime(), note that the DST_flag in the master locale rather than the "tm_isdst" field of the local tm structure determines the time zone display. EXAMPLE struct lconv my_locale; setlocale(LC_ALL, NULL); /* returns "C" */ my_locale = localeconv(); /* copy defaults */ my_locale.TZ_txt = {"PST","PDT"};/* set Pacific Daylight Time */ my_locale.TZ_secs=8*3600; my_locale.DST_flag = 1; my_locale.s_time = "CA dreaming"; setlocale(LC_TIME, NULL); /* returns "CA dreaming" */ setlocale(LC_ALL, "C"); /* returns "C", resets master */ SEE ALSO: localeconv(), strftime(), tzset() SETCAPS.FNC - Thu 23 Nov 89 00:20 - Page 198: NAME setcaps -- set the capslock status on PROTOTYPED IN: mflconio.h SYNOPSIS setcaps(); DESCRIPTION This is part of a set of functions which manipulate the keyboardf status flags at 0000:417 and 0000:418. setcaps() will force the caps lock flag ON, and clrcaps will force it off. EXAMPLE setcaps(); if(kbstate(2)) puts("Caps lock is now set"); else puts("Caps lock is NOT set"); clrcaps(); puts("Caps lock should now be off"); SEE ALSO _kbstate(), _kbstatus(), setnumlock(), clrnumlock(), clrcaps() SETDTR.FNC - Thu 23 Nov 89 00:20 - Page 199: NAME setdtr -- set state of data terminal ready flag PROTOTYPED IN: mflsys.h SYNOPSIS void setdtr(port, mode); int port; 0, 1, 2, or 3 (for COM1-COM4) int mode; TRUE to set flag, FALSE to clear flag DESCRIPTION This assembly language function provides direct access to the serial communications chips for the fastest access possible. Each function sets a particular communications output bit to the condition stated by "mode". The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in MFLDEFS.H. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ setdtr(sport, YES); /* take the modem offhook */ SEE ALSO: setdtr() SETFTIME.FNC - Thu 23 Nov 89 00:20 - Page 200: NAME setftime -- set a file's time/date stamp PROTOTYPED IN: mfltime.h PORTABILITY: TC SYNOPSIS r = setftime(fh, t); int r; returns 0 if successful, else -1 and sets errno int fh; handle of file to check struct ftime *t; pointer to file time/date stamp structure DESCRIPTION This routine sets a file's time/date stamp. See MFLTIME.H for a description of the ftime structure. EXAMPLE struct ftime then; int fh; fh = open ("file.ext", O_RDONLY); if (ERROR == setftime(fh, &then)) puts("couldn't reset time/date stamp"); } SEE ALSO: getftime(), touch(), get_filetime() SETNMLOC.FNC - Thu 23 Nov 89 00:20 - Page 201: NAME setnumlock -- Turns Numlock status flag on PROTOTYPED IN: mflconio.h SYNOPSIS setnumlock(); DESCRIPTION This is one of a set of functions which manipulate the keyboardf status flags at 0000:417 and 0000:418. setnumlock() sets the numlock status flag on. EXAMPLE setnumlock(); if(kbstate(2)) puts("Num lock is now set"); else puts("Num lock is NOT set"); clrnumlock(); puts("Num lock should now be off"); SEE ALSO: clrcaps(), setcaps(), clrnumlock(), _kbstate(), _kbstatus() SETPORT.FNC - Thu 23 Nov 89 00:20 - Page 202: NAME setport -- set port configuration PROTOTYPED IN: mflsys.h SYNOPSIS (void) setport(port, r); int port; port number int x; TRUE if condition exists, else FALSE (0) DESCRIPTION This is part of a set of very low level (direct port access) subroutines to enable I/O through COM1 through COM4. Only setport() uses BIOS int 14H. These functions are not intended to be the ultimate in async functions, but a starting point for an integrated set of async functions, and a means of getting at the serial port directly for speed and to work around the problems that some "clone" BIOS routines have in returning proper status values. File "smdefs.h" contains #defines to handle these ports mnemonically. The value to use for the setport() function is an 8-bit value, bitwise organized as follows: bits 1,0: 10 = 7-bit data, 11 = 8-bit data bit 2: 0 = 1 stop bit, 1 = 2 stop bits bits 4,3: x0 = No Parity, 01 = odd, 11 = even bits 7,6,5: baud rate: 000 = 110 baud (use 2 stop bits) 001 = 150 baud 010 = 300 baud 011 = 600 baud 100 = 1200 baud 101 = 2400 baud 110 = 4800 baud 111 = 9600 baud SETPORT.FNC - Thu 23 Nov 89 00:20 - Page 203: EXAMPLE /* this routine receives characters from COM1 at one ** speed and resends them to COM2 at another speed */ unsigned char i; setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity, ** 8-bits, 1 stop bit */ setport(SER2, 0xc3); /* set COM2 the same, except 4800 baud */ while(TRUE) { if(!ready_rcv(SER1)) continue; /* wait for a char */ i = readchar(SER1); /* fetch it */ while(!ready_xmt(SER2));/* wait for xmittr to be ready */ writechar(SER2, i); /* then send it */ } SEE ALSO: ready_rcv(), ready_xmt() SETRTS.FNC - Thu 23 Nov 89 00:20 - Page 204: NAME setrts -- set state of ready to send flag PROTOTYPED IN: mflsys.h SYNOPSIS void setrts(port, mode); int port; 0, 1, 2, or 3 (for COM1-COM4) int mode; TRUE to set flag, FALSE to clear flag DESCRIPTION This assembly language function provides direct access to the serial communications chips for the fastest access possible. The function sets the state of the ready to send flag. The port parameter may be specified as integers 0-3, or SER1 to SER4 as defined in <MFLDEFS.H>. EXAMPLE int sport; /* serial port */ sport = SER2; /* let it point to COM2 */ setrts(sport, YES); /* take the modem offhook */ SEE ALSO: setdtr() SFGETC.FNC - Thu 23 Nov 89 00:20 - Page 205: NAME sfgetc -- get a character from a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfgetc(stream); int r; character or EOF SFILE *stream; stream from which to read DESCRIPTION The sfgetc() function is an exact analog of the normal fgetc() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *infile; int ch; infile = sfopen("file.ext", "r"); /* input from a file */ if (EOF == (ch = sfgetc(infile))) puts("all done"); SEE ALSO: sfopen(), scopen(), sclose(), sfgets(), sfread(), sfputc(), sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SFGETS.FNC - Thu 23 Nov 89 00:20 - Page 206: NAME sfgets -- get a string from a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfgetc(buf,n,stream); char *r; string which was read char *buf; buffer to receive string int n; maximum size plus 1 of received string SFILE *stream; stream from which to read DESCRIPTION The sfgets() function is an exact analog of the normal fgets() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *infile; char str[128]; infile = sfopen("file.ext", "r"); /* input from a file */ if (NULL == sfgets(str, 128, infile))) puts("all done"); SEE ALSO: sfopen(), scopen(), sclose(), sfgets(), sfread(), sfputc(), sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SFINST.FNC - Thu 23 Nov 89 00:20 - Page 207: NAME sfinstall -- install a user-defined stream filter PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfgetc(stream,filt); int r; SUCCESS or ERROR SFILE *stream; stream to be filtered SFILTER *filt; filter to install DESCRIPTION The sfinstall() function allows user-defined filters to be installed in any stream opened using sfopen() or scopen(). Simple filters are installed by simply filling in the chain and (optionally) flush fields of an SFILTER structure and passing it to sfinstalll(). More complex filters which require initialization, etc. require dedicated installation functions which internally must call sfinstall(). An example of such a filter is the data encryption filter, installed using the crypt_install() function. Properly written filters can be chained indefinitely. Filter functions are invoked in a last-installed, first-executed sequence. When a stream is closed, the flush functions are invoked in the same order to clear any pending operations. EXAMPLE SFILE *infile; infile = sfopen("file.ext", "r"); /* input from a file */ crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */ sfinstall(infile, ucase_filt); /* after converting to UC */ SEE ALSO: sfopen(), scopen(), sclose(), crypt_install(), ucase_filt, lcase_filt SFOPEN.FNC - Thu 23 Nov 89 00:20 - Page 208: NAME sfopen -- open a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfopen(fname,mode); SFILE *r; pointer to an SFILE record - equivalent to fopen's FILE pointer - NULL in case of error char *fname; name of the file or stream to open char *mode; mode in which to open the streeam DESCRIPTION The sfopen() function is an almost exact analog of the standard fopen() function, so it is appropriate to describe their differences: o sfopen() returns an SFILE pointer while fopen() returns a FILE pointer. o sfopen'ed files and streams are always opened in binary mode o sfopen'ed files and streams are always read and written sequentially, i.e. there are no positioning commands comparable to fseek() o sfopen'ing a file or stream in append mode is not permitted o sfopen'ed files and streams allow user-defined filters to be installed, comparable to DOS command line pipes o a comparable function, scopen() exists to open streams to channels, e.g. an SFILE pointer may transparently refer to an interrupt-driven serial I/O package EXAMPLE SFILE *infile; if (NULL == (infile = sfopen("file.ext", "r+"))) puts("couldn't open file.ext"); SEE ALSO: scopen(), sclose() SFPUTC.FNC - Thu 23 Nov 89 00:20 - Page 209: NAME sfputc -- put a character to a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfputc(ch,stream); int r; character or EOF in case of error int ch; character to output SFILE *stream; stream to write DESCRIPTION The sfputc() function is an exact analog of the normal fputc() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *outfile; outfile = sfopen("file.ext", "w"); /* output to a file */ if (EOF == sfputc('x', outfile)) puts("oops"); SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(), sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SFPUTS.FNC - Thu 23 Nov 89 00:20 - Page 210: NAME sfputs -- put a string to a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfputc(s,stream); int r; SUCCESS if succesful char *s; string to output SFILE *stream; stream to write DESCRIPTION The sfputs() function is an exact analog of the normal fputs() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *outfile; outfile = sfopen("file.ext", "w"); /* output to a file */ if (EOF == sfputc("test", outfile)) puts("oops"); SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(), sfputc(), sfwrite(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SFREAD.FNC - Thu 23 Nov 89 00:20 - Page 211: NAME sfread -- read a buffer from a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfgetc(buf,size,n,stream); int r; number of complete elements which were read char *buf; buffer to receive data unsigned size; size of elements to be read unsigned n; number of elements to read SFILE *stream; stream from which to read DESCRIPTION The sfread() function is an exact analog of the normal fread() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *infile; char buf[1024]; infile = sfopen("file.ext", "r"); /* input from a file */ if (1024 != sfread(buf, 8, 128, infile)) puts("all done"); SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfputc(), sfputs(), sfwrite(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SFWRITE.FNC - Thu 23 Nov 89 00:20 - Page 212: NAME sfwrite -- write a buffer from a stream PROTOTYPED IN: mflfiles.h SYNOPSIS r = sfgetc(buf,size,n,stream); int r; number of complete elements which were written char *buf; buffer to write unsigned size; size of elements to write unsigned n; number of elements to write SFILE *stream; stream to write DESCRIPTION The sfwrite() function is an exact analog of the normal fwrite() function except that it is passed an SFILE pointer rather than a FILE pointer. EXAMPLE SFILE *outfile; char buf[1024]; outfile = sfopen("file.ext", "w"); /* output to a file */ if (1024 != sfwrite(buf, 8, 128, outfile)) puts("oops"); SEE ALSO: sfopen(), scopen(), sclose(), sfgetc(), sfgets(), sfread(), sfputc(), sfputs(), sfinstall(), crypt_install(), ucase_filt, lcase_filt SOUNDOFF.FNC - Thu 23 Nov 89 00:20 - Page 213: NAME soundoff -- turn off the speaker PROTOTYPED IN: mflsound.h SYNOPSIS void soundoff(); DESCRIPTION This is a very low level function to manipulate the speaker port control. It may be used with any function, but was developed for use with the mktone() function. Timer values should be set before turning the speaker on. SEE ALSO: soundon() SOUNDON.FNC - Thu 23 Nov 89 00:20 - Page 214: NAME soundon -- turn on the speaker PROTOTYPED IN: mflsound.h SYNOPSIS void soundon(); DESCRIPTION This is a very low level function to manipulate the speaker port control. It may be used with any function, but was developed for use with the mktone() function. Timer values should be set before turning the speaker on. SEE ALSO: soundoff() STR_ADD.FNC - Thu 23 Nov 89 00:20 - Page 215: NAME string_add -- BASIC-style string concatenation PROTOTYPED IN: mflstrng.h SYNOPSIS s = char *string_add(string,...,NULL); char *s; target string char *string; source string DESCRIPTION This is an emulation of the BASIC "A$=B$+C$" facility. It returns a concatenated string of its argument strings. This function uses the stralloc() funtion to allocate memory for the returned string. This memory is maintained in a circular pool and reused. See stralloc() for further information. Use strdup() or strcpy() to save the returned string in more permanent storage. EXAMPLE char *a = "European"; char *b = "Hardware"; char *c = "Skaters"; a = string_add(left(a,2),right(b,2),mid(c,2,2),NULL)); puts(a); /* prints "Eureka" */ SEE ALSO: right(), left(), mid(), str_init(), stralloc(), str_free() STR_FREE.FNC - Thu 23 Nov 89 00:20 - Page 216: NAME str_free -- free's the string pool PROTOTYPED IN: mflstrng.h SYNOPSIS str_free(); DESCRIPTION The str_free()function frees the memory used by stralloc() as a circular buffer of strings. EXAMPLE str_free(); SEE ALSO: str_init(), stralloc() STR_INIT.FNC - Thu 23 Nov 89 00:20 - Page 217: NAME str_init -- initialize a string pool PROTOTYPED IN: mflstrng.h SYNOPSIS r = str_init(size,number); int r; returns zero if successful, else ERROR int size; size of pre-allocated strings int number; number of pre-allocated strings (must be <= 128 in S or M models, or <=512 in C and L models) DESCRIPTION The underlying function for the BASIC-like string handling package is stralloc which maintains a pool of character buffers which it dispenses as requested and constantly reuses and reallocates as required. As a default, stralloc maintains a circular buffer of 16 strings in Tiny, Small, and Medium models and 64 strings in Compact and Large models. These start out very small and grow as required. Should you wish to expand the number of strings or wish to pre-allocate strings of a given minimum size to avoid re- allocation, the str_init() function allows setting both parameters. You should use str_init() and set the global variable "STRALLOC_OK" to "FALSE" prior to using any of the other functions in any routine which explicitly calls free() to de-allocate memory. The str_init() function internally calls str_free() which may be used to free all memory in use by these functions. It is NOT generally recommended that str_free() be called by an application program since "holes" in memory may be created that DOS is later unable to resolve. EXAMPLE str_init(81, 50); /* Pre-allocate 50-80 char strings */ SEE ALSO: stralloc(), str_free() STR_TERM.FNC - Thu 23 Nov 89 00:20 - Page 218: NAME STRING_TERMINATOR -- returns terminating '\0' DEFINED IN: mflstrng.h SYNOPSIS r = STRING_TERMINATOR(string); char r; terminating '\0' in string char *string; string to process DESCRIPTION This is one of the macros included in MFLSTRNG.H. It simply returns evidence of a terminating '\0' in a string. It is occasionally useful when concatenating or processing strings to refer to `&STRING_TERMINATOR(str)' which is a pointer to the end of `str'. EXAMPLES char *string = "Hello World\0"; if(STRING_TERMINATOR(string) == '\0') puts(Yep, it's got a terminator); SEE ALSO: LAST_CHAR(), NEXT_TO_LAST_CHAR() STRALLOC.FNC - Thu 23 Nov 89 00:20 - Page 219: NAME stralloc -- allocate a string from a string pool PROTOTYPED IN: mflstrng.h SYNOPSIS extern LOGICAL STRALLOC_OK; s = stralloc(size); char *s; returns a char buffer of length size, else NULL if out of memory int size; length of desired string Note: The LOGICAL data type is typedef'ed in MFLDEFS.H. STRALLOC_OK grants permission for stralloc() to resize any existing string should it be shorter than requested. To avoid this situation, you may pre-allocate all the strings in the pool to a specified size using str_init(), below. DESCRIPTION This function supports the BASIC-like string functions. The underlying function is stralloc() which maintains a pool of character buffers which it dispenses as requested and constantly reuses and reallocates as required. As a default, stralloc maintains a circular buffer of 16 strings in Tiny, Small, and Medium models and 64 strings in Compact and Large models. These start out very small and grow as required. Should you wish to expand the number of strings or wish to pre-allocate strings of a given minimum size to avoid re- allocation, the str_init() function allows setting both parameters. Since the strings are allocated from a circular buffer, if these routines are used within a recursive routine, it is strongly recommended that their results be copied (using strcpy() or strdup()) into their own dedicated space. If the result is copied into a malloc'ed string which subsequently is free'd, you should pre-allocate the string pool using str_init(), as noted above. EXAMPLE char *a; a = stralloc(MAX_FLEN); /* Grabs reusable string space large enough for a filename */ SEE ALSO: str_init(), str_free() STREQ.FNC - Thu 23 Nov 89 00:20 - Page 220: NAME STREQ -- compares strings TRUE/FALSE DEFINED IN: mflstrng.h SYNOPSIS r = STREQ(s1,s2); LOGICAL r; TRUE if strings match, else FALSE char *s1,*s2; strings to compare DESCRIPTION This is one of the macros included in MFLSTRNG.H. The STREQ and STREQI macros are simply aliases to encapsulate strcmp() and strcmpl() so the return is inverted from its normal sense. EXAMPLES char *string1, string2; if (STREQ(string1,string2)) puts("the strings match"); else pust("no match, but it reads more logically"); SEE ALSO: STREQI() STREQI.FNC - Thu 23 Nov 89 00:20 - Page 221: NAME STREQI -- compares strings TRUE/FALSE, UC/LC PROTOTYPED IN: mflstrng.h SYNOPSIS r = STREQI(s1,s2); LOGICAL r; TRUE if strings match, else FALSE. Case is ignored. char *s1,*s2; strings to compare DESCRIPTION This one of the macros included in MFLSTRNG.H. The STREQ and STREQI macros are simply aliases to encapsulate strcmp() and strcmpl() so the return is inverted from its normal sense. EXAMPLES char *string1, string2; if (STREQI(string1,string2)) puts("the strings match"); else pust("no match, but it reads more logically"); SEE ALSO: STREQ() STRFTIME.FNC - Thu 23 Nov 89 00:20 - Page 222: NAME strftime -- convert data in tm structure to a string PROTOTYPED IN: mfltime.h PORTABILITY: ANSI - strftime() is fully compliant including locale support SYNOPSIS r = strftime(buf,siz,fmt,tim); int r; length of the formatted string char *buf; buffer to receive the formatted string int siz; size of the buffer struct tm *tim; date/time data to format DESCRIPTION The strftime() function is defined in the ANSI draft but rarely implemented. It is like a printf() for time and date information. Country-specific formatting information may be specified - see setlocale(). The conversion characters supported by strftime() are: %a 3-character abbreviated weekday, e.g. Thu %A weekday name, e.g. Thursday %b 3-character abbreviated month, e.g. Jul %B month name, e.g. July %c standard format, e.g. Jul 13 14:27:39 1989 %d day of the month (01-31) %H hour of the day (00-23) %I hour of the day (01-12) %j day of the year (001-365) %m month (01-12) %M minutes (00-59) %p AM/PM indicator, e.g. PM %S seconds (01-59) %U week (starting Sundays) of the year (01-53) %w weekday (0-6, Sunday = 0) %W week (starting Mondays) of the year (01-53) %x date, e.g. Jul 13 1989 %X time, e.g. 13:27:39 %y year (00-99) %Y year with century (1970-2069) %Z time zone (from TZ_txt & DST_flag), e.g. CST %% literal '%' character STRFTIME.FNC - Thu 23 Nov 89 00:20 - Page 223: EXAMPLE #include <locale.h> extern struct LOC_TIME *loc_time; char buf[81]; setlocale(LC_TIME, "C"); /* set defaults */ strftime(buf, 80, "%A %c (day %j)", t); /* buf = "Thursday Jul 13 14:27:39 1989 (day 194)" */ strftime(buf, 80, "%A, %B %d, %Y, %I:%M:%S %P %z", t); /* buf = "Thursday, July 13, 1989, 02:27:39 PM CST" */ loc_time->TZ_txt = {"MST", "MDT"}; loc_time->DST_flag = 1; strftime(buf, 80, "%d %b %y (%a) %H:%M:%S %z", t); /* buf = "13 Jul 89 (Thu) 14:27:39 MDT" */ SEE ALSO: set_locale(), localeconv(), tzset() STRIP.FNC - Thu 23 Nov 89 00:20 - Page 224: NAME strip -- strip a newline from a string PROTOTYPED IN: mflstrng.h SYNOPSIS void strip(str); char *str; DESCRIPTION If the specified string terminates with a newline (\n) character, this function will replace the character with a NULL. EXAMPLE char str[] = "This is a string\n"; strip(str); the newline is stripped from str STRIXLAT.FNC - Thu 23 Nov 89 00:20 - Page 225: NAME strixlat -- translates characters based on tables PROTOTYPED IN: mflstrng.h SYNOPSIS r = strixlat(str,old,new); int r; number of characters changed, ERROR if size of `old' doesn't match size of `new' char *old; characters to change, case ingonred char *new; translated characters, case preserved DESCRIPTION This function replaces all occurrences of characters found in an input string and contained in a translation string to corresponding characters from a second translation string. EXAMPLE char *str="ABCxyzPpPpRrRr"; strxlat(str,"abc","1234"); /* returns ERROR */ strxlat(str,"XYZabc","xyzABC"); /* returns zero */ strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */ strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */ strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */ SEE ALSO: strxlat(), strnxlat(), strnixlat() STRNIXLT.FNC - Thu 23 Nov 89 00:20 - Page 226: NAME strnixlat -- translates first N characters based on tables PROTOTYPED IN: mflstrng.h SYNOPSIS r = strnixlat(str,old,new,n); int r; number of characters changed, ERROR if size of `old' doesn't match size of `new' char *old; characters to change, case ingonred char *new; translated characters, case preserved int n; translate first `n' occurances DESCRIPTION This function replaces the first N occurances of characters found in an input string and contained in a translation string to corresponding characters from a second translation string. EXAMPLE char *str="ABCxyzPpPpRrRr"; strxlat(str,"abc","1234"); /* returns ERROR */ strxlat(str,"XYZabc","xyzABC"); /* returns zero */ strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */ strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */ strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */ SEE ALSO: strxlat(), strnxlat(), strixlat() STRNXLAT.FNC - Thu 23 Nov 89 00:20 - Page 227: NAME strnxlat -- translates first N characters based on tables PROTOTYPED IN: mflstrng.h SYNOPSIS r = strnxlat(str,old,new,count); int r; number of characters changed, ERROR if size of `old' doesn't match size of `new' char *old; characters to change char *new; translated characters int n; translate first `n' occurances DESCRIPTION This function replaces the first N occurances of characters found in an input string and contained in a translation string to corresponding characters from a second translation string. EXAMPLE char *str="ABCxyzPpPpRrRr"; strxlat(str,"abc","1234"); /* returns ERROR */ strxlat(str,"XYZabc","xyzABC"); /* returns zero */ strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */ strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */ strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */ SEE ALSO: strxlat(), strixlat(), strnixlat() STRXLAT.FNC - Thu 23 Nov 89 00:20 - Page 228: NAME strxlat -- translates characters based on tables PROTOTYPED IN: mflstrng.h SYNOPSIS r = strxlat(str,old,new); int r; number of characters changed, ERROR if size of `old' doesn't match size of `new' char *old; characters to change char *new; translated characters DESCRIPTION This function replaces all occurances of characters found in an input string and contained in a translation string to corresponding characters from a second translation string. EXAMPLE char *str="ABCxyzPpPpRrRr"; strxlat(str,"abc","1234"); /* returns ERROR */ strxlat(str,"XYZabc","xyzABC"); /* returns zero */ strxlat(str,"xyzABC","MNOdef"); /* "defMNOPpPpRrRr" */ strixlat(str,"pr","ST"); /* "defMNOSsSsTtTt" */ strnixlat(str,"mno","ghi",2); /* "defGHOSsSsTtTt" */ SEE ALSO: strnixlat(), strnxlat(), strixlat() STUFF.FNC - Thu 23 Nov 89 00:20 - Page 229: NAME stuff -- get equipment report (high level) PROTOTYPED IN: mflsys.h SYNOPSIS r = _stuff(kind); int r; result of test int kind; kind of equipment to test for DESCRIPTION This function calls _stuff() and checks the appropriate bits returned depending upon the kind of information requested. Kind is one of the following: 0 = initial video mode mode 0, 2, or 7 returned 1 = number of disk drives 2 = number of printers 3 = number of serial ports 4 = joystick installed EXAMPLE int r; r = stuff(0); if(r == 7) printf("Monochrome card installed"); TIME2JUL.FNC - Thu 23 Nov 89 00:20 - Page 230: NAME time_to_julian -- convert time_t value to Julian date PROTOTYPED IN: mfltime.h SYNOPSIS r = time_to_julian(time); long r; Julian (scalar) date time_t time; date/time to convert DESCRIPTION This function converts date and time information, as expressed in standard time_t data types, to scalar (Julian) dates. Only the date information is preserved, the time is lost. EXAMPLE long jday; time_t tim; /* Get today's date */ jday = time_to_julian(time(&tim)); SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), ymd_to_julian(), tm_to_julian TM2JUL.FNC - Thu 23 Nov 89 00:20 - Page 231: NAME tm_to_julian -- convert tm structure to Julian date PROTOTYPED IN: mfltime.h SYNOPSIS r = tm_to_julian(t); long r; Julian (scalar) date struct tm *t; date/time data to convert DESCRIPTION This function converts date and time information, as included in standard tm structure, to scalar (Julian) dates. Only the date information is preserved, the time is lost. EXAMPLE long jday; time_t tim; struct tm *t; /* Get today's date */ time(&tim); jday = time_to_julian(localtime(&tim)); SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), ymd_to_julian(), time_to_julian TOUCH.FNC - Thu 23 Nov 89 00:20 - Page 232: NAME touch -- set file time/date stamp to the current time PROTOTYPED IN: mfltime.h PORTABILITY: Unix SYNOPSIS r = touch(file); int r; returns 0 if successful, else -1 char *file; file to set to curreent date & time DESCRIPTION The touch() function is similar to the unix command of the same name. Passed a file name, touch() sets its time/date stamp to the current time and date. EXAMPLE if (ERROR == touch("file.ext")) puts("couldn't update time/date stamp"); SEE ALSO: setftime() TRUNC.FNC - Thu 23 Nov 89 00:20 - Page 233: NAME trunc -- truncate an open'ed file PROTOTYPED IN: mflfiles.h SYNOPSIS result = trunc(fd,posn); int result; SUCCESS or ERROR int fd; handle of file to truncate long posn; size of truncated file DESCRIPTION The trunc() function will truncate a file that has been opened using the file handle open() call. It will return an ERROR if the truncation length is longer than the existing file. EXAMPLE int fd; FILE *fp; char *fname[] = {"file1","file2","file3"}; long sizes[] = 100L, 200L, 300L; fd = open(fname[0], O_WRONLY); fp = fopen(fname[1], "wb"); trunc(fd, sizes[0]); ftrunc(fp, sizes[1]); truncate(fname[2], sizes[2]); SEE ALSO: truncate(), ftrunc() TRUNCATE.FNC - Thu 23 Nov 89 00:20 - Page 234: NAME truncate -- truncate a named file PROTOTYPED IN: mflfiles.h SYNOPSIS result = truncate(fname,posn); int result; SUCCESS or ERROR char *fname; name of file to truncate long posn; size of truncated file DESCRIPTION This is one of the MFLIB routines which provide three different methods for truncating files to a given length - by name, handle or descriptor. They all work identically except that truncate() will check and return an ERROR if the truncation length is longer than the existing file. EXAMPLE int fd; FILE *fp; char *fname[] = {"file1","file2","file3"}; long sizes[] = 100L, 200L, 300L; fd = open(fname[0], O_WRONLY); fp = fopen(fname[1], "wb"); trunc(fd, sizes[0]); ftrunc(fp, sizes[1]); truncate(fname[2], sizes[2]); SEE ALSO: ftrunc(), trunc() UCASFILT.FNC - Thu 23 Nov 89 00:20 - Page 235: NAME ucase_filt -- a filter to force streams to upper case DECLARED IN: mflfiles.h SYNOPSIS r = sfinstall(stream,ucase_filt); int r; SUCCESS or ERROR SFILE *stream; stream to be filtered DESCRIPTION Not a function, ucase_filt is an SFILTER structure used with sfinstall() to force streams to upper case. EXAMPLE SFILE *infile; infile = sfopen("file.ext", "r"); /* input from a file */ crypt_install(infile, "keytxt", 0); /* encrypt using "keytxt" */ sfinstall(infile, ucase_filt); /* after converting to UC */ SEE ALSO: sfopen(), scopen(), sclose(), sfinstall(), crypt_install(), lcase_filt UNIX2DOS.FNC - Thu 23 Nov 89 00:20 - Page 236: NAME unix2dos -- converts Unix-style paths to DOS-style PROTOTYPED IN: mflfiles.h SYNOPSIS path = unix2dos(path); char *path; pathname to convert DESCRIPTION unix2dos() converts Unix-style filenames (i.e. using the "/" character as a path separator) to DOS-style. EXAMPLE puts(unix2dos("unix_dos/style/path/name.ext")); /* Prints "UNIX_DOS\STYLE\PATH\NAME.EXT" */ SEE ALSO: flnorm(), fln_fix() USECCLK.FNC - Thu 23 Nov 89 00:20 - Page 237: NAME usec_clock -- read the system clock in microseconds PROTOTYPED IN: mfltime.h SYNOPSIS t = usec_clock(); uclock_t r; returns zero if first call, thereafter returns microseconds elapsed DESCRIPTION This is one of a group of timing functions with an accuracy of one microsecond on IBM and closely compatible computers. To function properly, these functions require the host system to use either an 8253 or 8254 counter/timer chip based at I/O address 40h to generate the 18.2 Hz system interrupt used by DOS. These functions further assume that DOS uses the four bytes at 40:6C for its timekeeping function. These have proven to be safe assumptions for all IBM PC's and PS/2's, Compaq's, as well as most other clone computers and single-board computers designed for MS/PC-DOS compatibility. The sole exception is msec_pause() which requires the counter/timer chip but makes no other assumptions. The key function is usec_clock() which is a microsecond-accurate replacement for the normal clock() function. Just as the time returned by clock() may be converted to seconds by dividing by CLK_TCK, values returned by usec_clock may be similarly converted by dividing by UCLK_TCK, defined in MFLSYS.H. The usec_clock() function relies on data which rolls over at midnight each day and can handle this. However, if a program is to run continuously for many days, it becomes necessary to take action to prevent internal overflow. This may be done by resetting the internal registers used by usec_clock() at least once per day by calling restart_uclock(). USECCLK.FNC - Thu 23 Nov 89 00:20 - Page 238: EXAMPLE uclock_t time_1, time_2; int i; time_1 = usec_clock(); /* take an initial clock reading */ for (i = 1; i < 1000; ++i) { /* do things here but we don't know for how long */ } time_2 = usec_delay(500000L); /* pause 0.5 sec, note time */ do { /* do things here for 1.2345 seconds */ if (5000000L > usec_difftime(usec_clock() - time_1)) break; /* abort if total time is over 5 sec. */ } while (!timeout(time_2, usec_clock(), 1234500L)); SEE ALSO: restart_uclock(), usec_delay(), usec_difftime(), usec_timeout(), msec_pause() USECDIFF.FNC - Thu 23 Nov 89 00:20 - Page 239: NAME usec_difftime -- calculate the difference between two times DEFINED IN: mfltime.h SYNOPSIS diff = usec_difftime(start, end); uclock_t diff; microseconds elapsed between start & end uclock_t start; start time (from usec_clock()) uclock_t end; ending time (from usec_clock()) DESCRIPTION This is part of a set of timing functions with an accuracy of one microsecond on IBM and closely compatible computers. The key function is usec_clock() which is a microsecond-accurate replacement for the normal clock() function. Just as the time returned by clock() may be converted to seconds by dividing by CLK_TCK, values returned by usec_clock may be similarly converted by dividing by UCLK_TCK, defined in MFLTIME.H. Two differential time functions are provided; usec_difftime(), a macro which simply returns the difference between two usec_clock() readings, and usec_timeout() which tests for an expired time limit. EXAMPLE uclock_t time_1, time_2; int i; time_1 = usec_clock(); /* take an initial clock reading */ for (i = 1; i < 1000; ++i) { /* do things here but we don't know for how long */ } time_2 = usec_delay(500000L); /* pause 0.5 second, note time */ do { /* do things here for 1.2345 seconds */ if (5000000L > usec_difftime(usec_clock() - time_1)) break; /* abort if total time is over 5 sec. */ } while (!timeout(time_2, usec_clock(), 1234500L)); SEE ALSO: restart_uclock(), usec_clock(), usec_delay(), usec_timeout(), msec_pause() USECDLY.FNC - Thu 23 Nov 89 00:20 - Page 240: NAME usec_delay -- delay a given number of microseconds PROTOTYPED IN: mfltime.h SYNOPSIS end = usec_delay(usec); uclock_t end; usec_clock() value at end of delay uclock_t usec; number of microseconds to delay DESCRIPTION This part of a set of timing functions with an accuracy of one microsecond on IBM and closely compatible computers. To function properly, these functions require the host system to use either an 8253 or 8254 counter/timer chip based at I/O address 40h to generate the 18.2 Hz system interrupt used by DOS. These functions further assume that DOS uses the four bytes at 40:6C for its timekeeping function. These have proven to be safe assumptions for all IBM PC's and PS/2's, Compaq's, as well as most other clone computers and single-board computers designed for MS/PC-DOS compatibility. The sole exception is msec_pause() which requires the counter/timer chip but makes no other assumptions. Two delay functions are provided; usec_delay() which is passed a number of microseconds, and msec_pause() which is passed a number of milliseconds. Other than the time units, one difference between the two is that msec_pause() is slightly more portable as noted above. Another difference is that usec_delay() returns the value returned by usec_clock() when it finished. This is done in order to be able to chain time measurements. EXAMPLE uclock_t time_1, time_2; int i; time_1 = usec_clock(); /* take an initial clock reading */ for (i = 1; i < 1000; ++i) { /* do things here but we don't know for how long */ } time_2 = usec_delay(500000L); /* pause 0.5 second, note time */ do { /* do things here for 1.2345 seconds */ if (5000000L > usec_difftime(usec_clock() - time_1)) break; /* abort if total time is over 5 sec. */ } while (!timeout(time_2, usec_clock(), 1234500L)); SEE ALSO: restart_uclock(), usec_clock(), usec_difftime(), usec_timeout(), msec_pause() USECTOUT.FNC - Thu 23 Nov 89 00:20 - Page 241: NAME usec_timeout -- test for a timeout condition PROTOTYPED IN: mfltime.h SYNOPSIS stat = usec_timeout(start, end, usecs); LOGICAL stat; TRUE if time limit exceeded, else FALSE uclock_t start; start time (from usec_clock()) uclock_t end; ending time (from usec_clock()) uclock_t usecs; time limit in microseconds DESCRIPTION This is part of a set of timing functions with an accuracy of one microsecond on IBM and closely compatible computers. The key function is usec_clock() which is a microsecond-accurate replacement for the normal clock() function. Just as the time returned by clock() may be converted to seconds by dividing by CLK_TCK, values returned by usec_clock may be similarly converted by dividing by UCLK_TCK, defined in MFLTIME.H. Two differential time functions are provided; usec_difftime(), a macro which simply returns the difference between two usec_clock() readings, and usec_timeout() which tests for an expired time limit. EXAMPLE uclock_t time_1, time_2; int i; time_1 = usec_clock(); /* take an initial clock reading */ for (i = 1; i < 1000; ++i) { /* do things here but we don't know for how long */ } time_2 = usec_delay(500000L); /* pause 0.5 second, note time */ do { /* do things here for 1.2345 seconds */ if (5000000L > usec_difftime(usec_clock() - time_1)) break; /* abort if total time is over 5 sec. */ } while (!timeout(time_2, usec_clock(), 1234500L)); SEE ALSO: restart_uclock(), usec_clock(), usec_difftime(), usec_timeout(), msec_pause() VIDBORDR.FNC - Thu 23 Nov 89 00:20 - Page 242: NAME vid_border -- set border color PROTOTYPED IN: mflconio.h SYNOPSIS (void) vid_border(clr); int clr; one of the 16 color values DESCRIPTION This function and vid_palette manipulate the CGA card, or EGA card in CGA color mode. vid_border() sets the border color outside the normal text area to any of the 16 possible colors. vid_palette() sets the working color palette, and has meaning only in CGA mode 4 (color 320 x 200). palette # colors 0, 1, 2, 3 0 background, green, red, brown 1 background, cyan, magenta, white Call vid_palette() before using the vid_wrpix() function. In black&white 640 x 200 graphics mode, vid_border() will set the foreground color used for the display. The background will always be black. EXAMPLE vmode(CG320); /* set 320 color graphics mode */ vid_border(BLUE); /* set border and graphics background color */ vid_palette(1); /* select palette 1 */ vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2, which is magenta in palette 1 */ SEE ALSO: vid_palette() VIDPAGE.FNC - Thu 23 Nov 89 00:20 - Page 243: NAME vidpage -- set a video page as active page PROTOTYPED IN: mflconio.h SYNOPSIS void vidpage(page); int page; 0-7 depending upon mode DESCRIPTION This function sets the video display page to any page 0-7 subject to the effective video mode. Note that the monochrome card does not support video pages and therefore this function will have no effect. EXAMPLE vidpage(0); default lowest page VIDPALET.FNC - Thu 23 Nov 89 00:20 - Page 244: NAME vid_palette -- set color palette PROTOTYPED IN: mflconio.h SYNOPSIS (void) vid_palette(num); int clr; one of the 16 color values int num; palette 0 or 1 DESCRIPTION This function and vid_border() manipulate the CGA card, or EGA card in CGA color mode. vid_border() sets the border color outside the normal text area to any of the 16 possible colors. vid_palette() sets the working color palette, and has meaning only in CGA mode 4 (color 320 x 200). palette # colors 0, 1, 2, 3 0 background, green, red, brown 1 background, cyan, magenta, white Call vid_palette() before using the vid_wrpix() function. In black&white 640 x 200 graphics mode, vid_border() will set the foreground color used for the display. The background will always be black. EXAMPLE vmode(CG320); /* set 320 color graphics mode */ vid_border(BLUE); /* set border and graphics background color */ vid_palette(1); /* select palette 1 */ vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2, which is magenta in palette 1 */ SEE ALSO: vid_border() VIDRDPIX.FNC - Thu 23 Nov 89 00:20 - Page 245: NAME vid_rdpix -- read a pixel from the screen PROTOTYPED IN: mflconio.h SYNOPSIS (void) vid_rdpix(x, y, clr); int x, y; x and y screen coordinates int clr; one of the 4 color values for current palette DESCRIPTION This function and vid_wrpix() manipulate the CGA card, or EGA card in CGA graphics mode. vid_wrpix() will set the pixel at location x,y to the color clr, which is 0, 1, 2, or 3. The real color will be as set via vid_palette(). For black and white 640 graphics, use 0 or 1 only. vid_rdpix() will return the color value (0-3) at the specified x,y location. If using black&white 640 x 200 graphics mode on a CGA, then the color value for vid_wrpix should be 0 or 1. 0 will set the pixel to black (which is the background color), and 1 will set the pixel to the color which has been previously selected by vid_border() (the default is, of course, white). In BW640 mode, therefore, the pixels can only be turned on or off. There is no possibility of multi-color displays. These functions do not support the extra modes of the EGA or PGA adapters. EXAMPLE vmode(CG320); /* set 320 color graphics mode */ vid_border(BLUE); /* set border and graphics background color */ vid_palette(1); /* select palette 1 */ vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2, which is magenta in palette 1 */ SEE ALSO: vid_rdpix() VIDWRPIX.FNC - Thu 23 Nov 89 00:20 - Page 246: NAME vid_wrpix -- write a pixel to the screen PROTOTYPED IN: mflconio.h SYNOPSIS (void) vid_wrpix(x, y, clr); int x, y; x and y screen coordinates int clr; one of the 4 color values for current palette DESCRIPTION This function and vid_rdpix() manipulate the CGA card, or EGA card in CGA graphics mode. vid_wrpix() will set the pixel at location x,y to the color clr, which is 0, 1, 2, or 3. The real color will be as set via vid_palette(). For black and white 640 graphics, use 0 or 1 only. vid_rdpix() will return the color value (0-3) at the specified x,y location. If using black&white 640 x 200 graphics mode on a CGA, then the color value for vid_wrpix should be 0 or 1. 0 will set the pixel to black (which is the background color), and 1 will set the pixel to the color which has been previously selected by vid_border() (the default is, of course, white). In BW640 mode, therefore, the pixels can only be turned on or off. There is no possibility of multi-color displays. These functions do not support the extra modes of the EGA or PGA adapters. EXAMPLE vmode(CG320); /* set 320 color graphics mode */ vid_border(BLUE); /* set border and graphics background color */ vid_palette(1); /* select palette 1 */ vid_wrpix(10, 10, 2) /* write a pixel at x10, y10, color 2, which is magenta in palette 1 */ SEE ALSO: vid_rdpix() VINIT.FNC - Thu 23 Nov 89 00:20 - Page 247: NAME v_init -- obtains information on the video system PROTOTYPED IN: mflconio.h SYNOPSIS v_init(); DESCRIPTION The v_init() function analyzes the video system and filles in the global structure, v_info_, defined in MFLCONIO.H. Included in this structure are fields containing the following information: o The number of rows displyable on the active display o The number of columns displyable on the active display o The video mode of the active display o The active page of the active display o The screen segment of the active display o The screen address of the active display o A flag to signal if DesqView or TopView is active EXAMPLE v_init(); printf("displaying %d rows by %d cols\n", v_info_.rows, v_info_.cols); VISCROLL.FNC - Thu 23 Nov 89 00:20 - Page 248: NAME viscroll -- scrolls the video display up or down PROTOTYPED IN: mflconio.h PORTABILITY: Compatible with Blaise (tm) library function of the same name. SYNOPSIS void viscroll(lines,atr,tlrow,tlcol,brrow,brcol,dir); int lines; number of lines to scroll int atr; video attribute of new lines int tlrow; top left row int tlcol; top left column int brrow; bottom right row int brcol; bottom right column int dir; direction (SCR_UP or SCR_DN) DESCRIPTION The viscroll() function calls the BIOS video routines to directly scroll an area of the screen. The area to be scrolled is defined as a rectangular block whose upper left and bottom right co- ordinates are passed to viscroll(). As lines are scrolled, new ones appear to take their place whose video attribute is also specified. Finally, the direction to scroll is specified using the macro definitions SCR_UP and SCR_DN. If passed zero for the number of lines to scroll, the specified area is cleared to the specified attribute, acting like a windowed version of d_cls(). EXAMPLE viscroll(2,NORMAL,0,0,7,79,SCR_UP); /* scroll top 1/3 up 2 */ viscroll(0,REVERSE,8,0,15,79,SCR_UP); /* clear middle 1/3 */ viscroll(2,NORMAL,16,0,23,79,SCR_DN); /* scroll btm 1/3 dn 2 */ VMODE.FNC - Thu 23 Nov 89 00:20 - Page 249: NAME vmode -- set video mode PROTOTYPED IN: mflconio.h SYNOPSIS void vmode(mode); int mode; DESCRIPTION This function sets the video mode from 0 - 7. Modes are as specified in the DOS manual. The most common is Black & White 80 column mode, which is mode 2. This library package includes screen.h which defines video modes. EXAMPLE #include <screen.h> vmode(BW80); WEEKDAY.FNC - Thu 23 Nov 89 00:20 - Page 250: NAME weekday -- Determine the day of the week form the date PROTOTYPED IN: mfltime.h SYNOPSIS value = weekday(month, day, year); int value; returns 0-6 int month; number of month 1-12 int day; number of date 1-31 int year; year starting with 1980 DESCRIPTION This function returns the number of the day in the week for any date from January 1, 1980. Sunday is day 0, and Saturday is day 6. EXAMPLE for July 2, 1986: int value; value = weekday(7, 2, 1986); value for this date will be 3 (Wednesday) You may wish me a Happy Birthday. SEE ALSO: julian_to_dayname(), julian_to_wkday() WILDNAME.FNC - Thu 23 Nov 89 00:20 - Page 251: NAME wildname -- matches filenames against a pattern PROTOTYPED IN: mflfiles.h SYNOPSIS r=wildname(pat, str, rule); int r; zero if match, else non-zero char *pat; pattern to match - may contain wildcards char *str; filename to match int rule; universal wildcard rules - may be: 0 - no universal wildcards DOS_STYLE - "." matches anything UNIX_STYLE - "*" matches anything BOTH_STYLES - "*", or "." match anything DESCRIPTION There are times when you need to manually perform a wildcard pattern match on a filename rather than let DOS do it for you. There also times when you'd like the pattern matching to be a little smarter than DOS's. The wildname() function performs both services. Passed a pattern and a filename (no path or directory specs allowed, though), it will return a value similar to strcmp() if the filename matches the pattern. It is also smart enough to properly handle embedded '*' wildcards which DOS can't do. A '?' wildcard will match any character. A '*' wildcard may match zero or more occurances of any character(s). Optionally, wildname() allows either, both or neither DOS or Unix-style unversal pattern matching. The universal DOS pattern is "." and will match any file name. The universal Unix pattern is "*". The implicit universal pattern is "*.*" and will match any file name regardless of which style (if any) universal pattern is selected. Finally, note that if DOS style pattern matching is specified, the smart "*" wildcard pattern matching is disabled in order to fully emulate DOS's brain damaged wildcard processing. WILDNAME.FNC - Thu 23 Nov 89 00:20 - Page 252: EXAMPLES wildname("A*C.E?T", "ABC.EXT", 0); /* matches */ wildname("A*C.E?T", "ABX.EXT", 0); /* no match */ wildname("A*C.E?T", "ALEC.EXT", 0);/* matches */ wildname("A*C.E?T", "ABC.ET", 0); /* no match */ wildname("A*C.E*T", "ABC.ET", 0); /* matches */ wildname("*.*", "ABC.XYZ", 0); /* matches */ wildname(".", "ABC.XYZ", 1); /* matches */ wildname("*", "ABC.XYZ", 2); /* matches */ wildname(".", "ABC.XYZ", 3); /* matches */ wildname("*", "ABC.XYZ", 3); /* matches */ wildname("A*C.X*Z", "ABZ.XYC", 0); /* no match */ wildname("A*C.X*Z", "ABZ.XYC", 1); /* matches */ wildname("A*C.X*Z", "ABZ.XYC", 2); /* no match */ wildname("A*C.X*Z", "ABZ.XYC", 3); /* no match */ SEE ALSO: dirmask() WKDAYNM.FNC - Thu 23 Nov 89 00:20 - Page 253: NAME wkdayname -- return a pointer to name of day string PROTOTYPED IN: mfltime.h SYNOPSIS char *wkdayname(day); int day; day number 0-6 DESCRIPTION This function returns a character pointer to a text string naming the day of the week indicated by the day parameter. Day 0 is Sunday, and day 6 is Saturday. Strings are null terminated and may be used directly or copied to another string. EXAMPLE printf("Today is %s", wkdayname(3)); /* output is : Today is Wednesday */ WRTCHAR.FNC - Thu 23 Nov 89 00:20 - Page 254: NAME writechar -- send a char to the serial port PROTOTYPED IN: mflsys.h SYNOPSIS (void) writechar(port, r); unsigned char r; character to send or receive int port; port number DESCRIPTION This is part of some very low level (direct port access) subroutines included to enable I/O through COM1 through COM4. Only setport() uses BIOS int 14H. These functions are not intended to be the ultimate in async functions, but a starting point for an integrated set of async functions, and a means of getting at the serial port directly for speed and to work around the problems that some "clone" BIOS routines have in returning proper status values. File "MFLDEFS.H" contains #defines to handle these ports mnemonically. writechar() will place the specified unsigned char into the transmitter buffer register where it will be sent. If the program "loop" is short and fast enough, these functions will be ample to allow communications at up to 9600 baud. A program has already been implemented to communicate with a prom programmer at this rate, so it can be done. However, when the program does not poll the receiver fast enough it is likely that characters may be lost and the maximum usable baud rate will be lower. It is highly unlikely that baud rates less than 2400 baud will be necessary if the program is properly structured. EXAMPLE /* this routine receives characters from COM1 at one ** speed and resends them to COM2 at another speed */ unsigned char i; setport(SER1, 0xe3); /* set COM1 to 9600 baud, No parity, ** 8-bits, 1 stop bit */ setport(SER2, 0xc3); /* set COM2 the same, except 4800 baud */ while(TRUE) { if(!ready_rcv(SER1)) continue; /* wait for a char */ i = readchar(SER1); /* fetch it */ while(!ready_xmt(SER2));/* wait for transmitter to be ready */ writechar(SER2, i); /* then send it */ } SEE ALSO: readchar(), ready_rcv(), ready_xmt(), setport() YMD2JUL.FNC - Thu 23 Nov 89 00:20 - Page 255: NAME ymd_to_julian -- convert year, month, date to Julian date PROTOTYPED IN: mfltime.h SYNOPSIS r = ymd_to_julian(yr,mo,day); long r; Julian (scalar) date unsigned yr; year unsigned mo; month unsigned day; date DESCRIPTION This function converts dates expressed in days, months, and years into scalar (Julian) dates. EXAMPLE long jday; jday=ymd_to_julian(1974,6,9); SEE ALSO: julian_to_ymd(), julian_to_wkday(), julian_to_yrday(), julian_to_dayname(), julian_to_time(), julian_to_tm(), time_to_julian(), tm_to_julian _GETDI.FNC - Thu 23 Nov 89 00:20 - Page 256: NAME _getdi -- get device information for file handle PROTOTYPED IN: mflsys.h SYNOPSIS r = _getdi(fh); int r; status byte, low 8 bits only int fh; DOS file handle to investigate DESCRIPTION This function returns the lower 8 bits of the control word for the specified file handle, usually stdout, stdin, or one of the other standard channels. Note that a file handle, NOT file descriptor is required. Refer to the DOS manual for the description of all the bits. Bit 7 set indicates a character device, and bits 0,1 refer to the console. This function is called by the functions isatty() and iscons(). EXAMPLE int r; int fh; fh = fileno(stdout); /* get file handle for stdout */ r = _getdi(fh); if(r >= 0x80) printf("stdout is a character device"); _STUFF.FNC - Thu 23 Nov 89 00:20 - Page 257: NAME _stuff -- get equipment report (low level) PROTOTYPED IN: mflsys.h SYNOPSIS r = _stuff(); int r; DESCRIPTION Returns an integer from DOS int 11H, indicating the available equipment and initial video mode. This is a low level function. For a higher level function, refer to stuff(). bits 15, 14 = # of printers installed bit 12 = joystick installed if 1 bits 11-9 = # of serial ports installed bits 7-6 = # of disk drives, 1-4 if bit 0 = 1 bits 5-4 = Initial video mode: 01 40 x 25 b/w CGA 10 80 x 25 b/w CGA 11 80 x 25 Mono card bit 0 = no disk drives if 0 EXAMPLE int r; r = _stuff(); /* test bit 12 (game port) */ if((r & 0x1000) != 0) printf("Game port installed");