CharIo Function Reference

Infrasctucture CharIo Function Reference

CharIo


catChrs	catStamp	cpyFil	clkAdd	clkAddUs	clkCmp
clkDeltaMs	clkSub	dmpLin	dmpMem	fatal	fmtCat
fmtPut	fReName	fndFil	getDayNbr	getDom	getDow
getFile	getFilSiz	getHex	getHr	getInt	getKb
getMin	getMon	getNbr	getSec	getTxt	getYr
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	catStamp( char* ouput, char* fmt )

Get the current time, and concatenate the requested fields (see catDT in str.c) to the "output" string.

The format ("fmt") string is composed of percent signs "%" followed by a format character and may be separated by any other non-format characters ("%h:%m:%s").

The format characters are:


Y	-	year as yyyy.
AM	-	Ascii month name.
AD	-	Ascii day of week.
M	-	Numeric month of year (1-12).
D	-	numeric day of month (1-31).
Z	-	Time Zone.
h	-	Hour of the day.
m	-	minute of the hour.
s	-	seconds of the minute.
.	-	(dot) milliseconds of the second.
ˆ	-	(carat) Microseconds of the second.


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	clkCmp( clok_t* a, clok_t* b )

Compare clok_t *a to clok_t *b.

Returns 0 if they are equal, -1 if a < b and +1 if a > b.


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).


int	getDom()

Return the Unix day of the month (1 - 31).


int	getDow( )

Return the Unix day of the week (0 = Sunday - 6 = Saturday).


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.


int	getHr( )

Return the Unix hour of the day (00 - 23).


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	getMin()

Return the Unix minute of the hour (00 - 59).


int	getMon() \

Return the Unix month (01 - 12).


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	getSec()

Return the Unix second of the minute (00 - 59).


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	getYr()

Return the Unix year (1900 - 2008).


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.


	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 "trc.txt" in the CWD.


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 "trc.txt" in the CWD.

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

"trc.txt" in the CWD.


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.