Infrasctucture CharIo Function Reference

CharIo
catChrs     cpyFil     clkAdd     clkAddUs     clkDeltaMs     clkSub    
dmpLin     dmpMem     fatal     fmtCat     fmtPut     fReName    
fndFil     getDayNbr     getFile     getFilSiz     getHex     getInt    
getKb     getNbr     getTxt     isHex     isKb     menu    
pntHex2dec     pntHex     rawIo     rdFil     setExtWat     setIoFlg    
setRecyl     utFatal     utTrc     utTrcErr     utTrcOff     utTrcOn    
wtFil     yesterday    

int  catChrs( char* ouput, char* fmt, ... (elipsis) )
Get alpha numeric text characters from the keyboard into the user supplied "output" buffer honor BS, CTL_c, etc.    If "fmt" is non-zero, it will be used, along with any following values to format and print an output message to stdout.    Note: the "output" buffer will be used temporarily to build the message.    Returns entered terminating character.

int  cpyFil( char* dest, char* src )
The text file indicated by "src" will be opend and copied to the location and name indicated by "dest".    Returns OK if all is well else ERR.

int  clkAdd( clok_t* out, clok_t* a, clok_t* b )
Add clok_t *a to clok_t *b, placing the result in clok_t *out.    Returns OK if all is well else ERR.

int  clkAddUs( clok_t* in_out, int usec )
Add usec to clok_t *in_out, placing the result in clok_t *in_out.    Returns OK if all is well else ERR.

int  clkDeltaMs( clok_t* a, clok_t* b )
Subtract clok_t *b from clok_t *a, returning the result converted to milliseconds.    Returns -1 if the delta time was negative and zero if delta was zero.

int  clkSub( clok_t* out, clok_t* a, clok_t* b )
Subtract clok_t *b from clok_t *a, placing the result in clok_t *out.    Returns OK if all is well else ERR.

int  dmpLin( char* output, char* input, int len, long addr )
Len bytes are dumped from input to output as an ascii string.    This is sometime called a hex dump in that the characters are interpreted as hexadecimal bytes and the ascii equivalents are printed at the end of the line.    The add field is printed at the left of the line, in hexadecimal.    This is usually used to dump one line (about 16 bytes) of hex.    The advantage of this call is that it can be used with a small output buffer.   

int  dmpMem( char* output, char* input, int len )
Len bytes are dumped from input to output as an ascii string.    The output is in 16 byte segments.    This call requires a very large buffer for the output.    The size of the buffer is len/16 * 78 or about 78 output bytes for each 16 bytes of input.   

int  fatal( char* fmt, ... elipsis )
Format the message, and print it on stderr, then exit.   

int  fmtCat( char* output, char* fmt, ... elipsis )
Handy as a pocket on a shirt.    Formats the supplied arguments per the format string to an ascii string which is concatenated to the output.

int  fmtPut( char* output, char* fmt, ... elipsis )
Same as fmtCat but doesn't concat, it just prints to the buffer.

int  fReName( char* filPath, char* file )
Find the file at "filPath", and rename it to "file".    Returns OK else ERR.

char*  fndFil( char* namPath, int pathDelim, char* name )
Search the "namPath", using "pathDelim" as a separator, until the file "name" is found.    Return a string containing the path and name suitable for a file open command else NULL.

int  getDayNbr( )
Return the Unix day number (Sunday = 0 ... Saturday = 6).

char*  getFile( char* namPath, char* path, char* name )
Use namePath, path, and name to find and read a file.    The entire file is returned in a single malloced ascii string, else NULL.

long  getFilSiz( char* namPath )
Return the size, in bytes, of the file pointed at by "namPath" else NOTFND.

long  getHex( )
Return the long integer equivalent of the ascii hexadecimal (0-9,a-f) of the keyboard entry.    getHex handles backspaces.

long  getInt( char* input )
Return the integer equivalent of the ascii decimal or hexadecimal (0-9,a-f) of the "input" string. Uses sscanf. An input of hexadecimal characters must begin with 'X' or '0X'.

int  getKb( )
Get a key from the keyboard, but you can substitute you own wait routine using setExtWat().

int  getNbr( char* msg )
Prompt with the ascii "msg", then accept input in ascii decimal (0-9) until a non-decimal or NEWLINE character is entered. Return an integer containing the value of the entered characters.

int  getTxt( char* ouput, int echo, int trm, char* fmt, ... (elipsis) )
Get alpha numeric text characters from the keyboard into the user supplied "output" buffer honor BS, CTL_c, etc.    If "echo" is non zero it will be treated as the echo character for each input character.    If "trm" (terminator) is non-zero it will be searched for as the terminator character.    If "fmt" is non-zero, it will be used, along with any following values to format and print an output message.    Note: the "output" buffer will be used temporarily to build the message.    Returns entered terminating character.

int  isHex( int chr )
Return TRUE if the input character "chr" is an ascii 0-9 or a-f or A-F.

int  isKb( int timOut )
Retuns OK is a keyboard character is available, else FALSE if times out. "timOut" is in miliseconds.

int  menu( menu_t* menu, char* prompt )
Displays and navigates a family of menus constructed from menu_t structures.    The menu is an array of menu_t structures, the first entry of which, just displays in the menu prompt.    Each additional entry contains, in order, The prompt selection name (prompt), a conditional flag (cond), a function to call, the argument for that called function, and a menu name.
typedef struct menu {
     char      *prompt;
     int                   *cond; // CONDITIONAL INCLUSION OF MENU ITEM
     pfi_t      func; // CHARACTER PROCESSING FUNCT() PTR
     void      *arg; // ARGUMENT PASSED TO PROCESSING FUNCT()
     void                   *nxt; // NEXT MENU IF FUNC RETURNS TRUE
     }menu_t;

One of three different actions may be triggered by entering a menu selection.    If the arg field is set to an int pointer and the nxt field contains a value the value will be stored in the the integer pointed to by arg.    If a function pointer is in "func" the function will be called and passed "arg" as an argument.    If another menu pointer is in "nxt" control will be transferred to it.    The "prompt" will be displayed at the left of the selection menu and each menu level will append it's own prompt or level name.    Each menu is an array of menu_t.    Other Menu arrays can be linked via the "nxt" menu entry.
The first line in the menu (after MNU_BGN()) simply states the Menu's name.
MNU_BGN( Menu1 )
     { "The Test Menu" 0, NULL, 0, 0 },
     { "MakeItSo" &Flag, NULL, 0, Menu2 },
     { "iseeYou" 0, seeYou, 12, NULL },
MNU_END
Note Menu2 must be defined prior to Menu1.    Menu1, above, will produce the menu below if Flag is true.
"[TestMenu] MakeItSo, iseeYou Quit ->"
The first upper case letter in each entry selects that entry.    In the test menu above the name "TestMenu" is given.    The first selection "MakeItSo" will not appear until the conditional flag "Flag" is true.    And when it is visible, selecting the letter 'm' will cause the system to transition to Menu2.    The second selection "iseeYou" will be selected when the letter 'Y' is entered, in which case the function seeYou() will be called and passed the argument 12.    The "Quit->" is automatically appended to all menus and if the letter 'q' is entered, the menu() function returns to the previous (higher) menu.    The called functions have one argument of type void* which is the entry in argument 4 of the menu structure.    The called functions normally return 1 which causes the menu() function to stay on the current menu.    If the called function reutrns a zero, menu() will return to the prevous (higher) menu.

int  pntHex2dec( uchar* out, char* in )
Print a hexadecimal array as a string of comma seperated decimal numbers.    Returns the output length.

int  pntHex( char* in, int len )
Print a hex array "in" of lenth "len" as comma seperated decimals.

int  rawIo( int ctrl )
If "ctrl" is non zero, put the terminal into "RAW" mode, that is, turn off canonical processing, echoes, etc. This allows reading and printing characters from/to the keyboard/screen directly without requiring an "Enter" key after each. After Raw Mode is entered another call to rawIo() with "ctrl" = zero restores normal terminal mode.

char*  rdFil( char* filName )
Open and read the text file referenced by "filName", allocating a suitable buffer.    Returns the pointer to the buffer containing the entire file, else NULL if an error occured.    The returned pointer must be free()'d after use.

int  setExtWat( pfi_t extWaitFunc )
Sets the function to be used by getKy() as it's wait function. This is in case you need to listen for other interrupts.

int  setIoFlg( int fd, int flg )
Sets flags on the open fd. An fcntl is done on the open fd, the new flags logically Ored into the flags then another fcntl to set the new flag values.

int  setRecyl( int timOut )
May be used with menu() to set time out against it's keyboard read. At time out, the last key will be re-executed.

int  utFatal( char* fmt, ... elipsis )
UtTrc, utFatal, utTrcErr are the utility library's version of trc, trcErr, and trcFatal. They trace directly to a file in the local directory called "trace".

int  utTrc( int level, char* fmt, ... elipsis )
UtTrc, utFatal, utTrcErr are the utility library's version of trc, trcErr, and trcFatal.    They trace directly to a file in the local directory called "trace".    These trace functions support level enable by using:
            #undef UTMSK
            #define UTMSK SETUTMSK( LevelNumber )
You may assign a level to each module of the executable source code using these macros, then use the UTTRCENA keyword in the configuration file or "TRC_ENA" in the process' environment to enable any layer or group of layer's tracing.
            UTTRCENA 2+3+5,55
or:
            export TRC_ENA=2+3+5,55
Would enable modules 2, 3, and 5 with a trace level of 55.

int  utTrcErr( char* fmt, ... elipsis )
UtTrc, utFatal, utTrcErr are the utility library's version of trc, trcErr, and trcFatal. They trace directly to a file in the local directory called "trace".

int  utTrcOff( )
Temporarily turn util tracing off.

int  utTrcOn( )
Temporarily turn util tracing on.

int  wtFil( char* dest, char* fileDat )
The string is written to text file "dest".    Returns OK if all is well, else ERR.

int  yesterday( int dayNbr )
When called with a UNIX day number (0-6) it will return the nubmer of the previous day, observing end of week wraparound.