head     1.2;
access   ;
symbols  ;
locks    bin:1.2;
comment  @@;


1.2
date     91.05.13.13.51.44;  author bin;  state Exp;
branches ;
next	1.1;

1.1
date     91.03.28.18.32.21;  author bin;  state Exp;
branches ;
next	;


desc
@initial version provided by cef
@


1.2
log
@style changes by cef at steve's request
@
text
@misc/Read_me 10/11/90

libmisc.a is a collection of miscellaneous useful user functions
which can be used by C programmers to increase productivity.

misc.h
	Is a header file with externs and #define's for the
	various functions in libmisc.a

larges.h
	Is a header file for model independent assembler with some
	nice macros like Enter() and Leave. memxch is a good example
	of a user.

char * alloc(n) unsigned n;
	malloc() n bytes and zero them, or put out a fatal error message.

int approx(a, b) double a, b;
	If a and b are within epsilon return 1 else 0. epsilon
	is a visable double.

char * ask(reply, msg, ...) char *reply *msg;
	Puts out msg as a printf style format string using any
	trailing arguments. Gets a line from stdin with gets()
	and returns the address of reply. For example
	sscanf(ask(buff, "%d numbers", 3), &a, &b, &c);
	puts out the message "Enter: 3 numbers " gets a reply
	in buff and hands that to sscanf().

void banner(word, pad) char *word; int pad;
	Prints word as a banner on stdout preceeded by pad
	spaces. Each letter of the banner is composed of
	occurances of itself.
	
unsigned short crc16(p) char *p;
	Takes the crc16 of the string p and returns it. Fast
	and perfect for hash tables, diff algorithms etc.

void fatal(msg, ...) char *msg;
	Prints the msg as a printf style format string using
	any trailing arguments. This is preceeded by
	"\nfatal". fatal() then does exit(1).

char * getline(ifp, lineno) FILE *ifp; int *lineno;
	Function to get lines from an input file.
	Returns the address of the line, or NULL for eof.

	lineno should usually be started at 1. lineno will
	be incremented by the number of lines in the previous call.
	Thus lineno will be the number of the line just gotten.

	# to end of line is passed.
	\ whitespace through end of line is passed.
	\n newline
	\p #
	\a alarm
	\b backspace
	\r carrage return
	\f form feed
	\t tab
	\\ backslash
	\ddd octal number
	all other \ sequences are errors and reported on stderr.

void splitter(ofp, line, limit) FILE *ofp; char *line; int limit;
	Output line to ofp splitting it into chunks less than
	limit. Inserts \ between chunks and attempts to do this
	on whitespace boundarys. Splitter will produce a long line
	rather than split on non whitespace. If line does not end in
	\n splitter will add one.

int is_fs(special) char *special;
	Checks if a special file is a well formed file system.
	Users should never put file systems on /dev/ram1 but
	For multi system software like compress it is smart
	to test.

	Return values:
	-1	Not a device, cannot open, read or seek failed.
	 0	No filesystem.
	 1	Legal filesystem.

char * lcase(str) char *str;
	Converts str to lower case.

char * match(string, pattern, fin) char *string, *pattern, **fin;
	Like pnmatch() except match returns the address of the
	pattern matched. fin is aimed past the end of the
	pattern found. That is match finds a pattern and tells
	you where it is.

void memxch(s1, s2, len) char *s1, *s2;
	Exchanges s1 and s2 for len. Fast and in assembler.

char * newcpy(str) char* str;
	Creates a NUL terminated copy of str on the heap.
	It calls fatal if there is no space.

char * pathn(name, envpath, deflpath, access)
    char *name, *envpath, *deflpath, *access;
	example: pathn("helpfile", "LIBPATH", "/lib", "r")
	Looks for helpfile using the environmental variable
	LIBPATH if that isn't set, or the second parm is NULL
	it uses the default path "/lib". The file found must
	have read permission. pathn() returns the full path
	to the file found.

double picture (dble, format, output )
    double dble;    /* the number to format */
    char  *format;  /* the format mask */
    char  *output;  /* the output area. At least as large as format */

	The picture() function gives C users far better
	numeric formatting ability than COBOL and BASIC users. 

	9    Provides a slot for a number.
	     5.000 passed through a mask of '999 CR' gives '005   '
	    -5.000 passed through a mask of '999 CR' gives '005 CR'
	 Note: C & R are not special to picture. Trailing non special
	       characters print only if the number is negitave
	
	Z    Provides a slot for a number but supresses lead zeros.
	  1034.000 passed through a mask of 'ZZZ,ZZZ' gives '  1,034'
	 Note: comma is not special to picture. Imbeded non special
	       characters print only if preceeded by significant digits
	
	J    Provides a slot for a number but shrinks out lead zeros.
	  1034.000 passed through a mask of 'JJJ,JJJ' gives '1,034'
	
	K    Provides a slot for a number but shrinks out any zeros.
	 70884.000 passed through a mask of 'K9/K9/K9' gives '7/8/84'
	
	$    Floats a dollar sign to the front of the displayed number.
	   105.000 passed through a mask of '$ZZZ,ZZZ' gives '    $105'
	
	.    Separates the number between decimal and integer portions.
	   105.670 passed through a mask of 'Z,ZZZ.999' gives '  105.670'
	
	T    Provides a slot for a number but supresses trailing zeros.
	   105.670 passed through a mask of 'Z,ZZ9.9TT' gives '  105.67 '
	
	S    Provides a slot for a number but shrinks out trailing zeros.
	   105.670 passed through a mask of 'Z,ZZ9.9SS' gives '  105.67'
	
	-    Floats a - in front of negitive numbers
	   105.000 passed through a mask of '-Z,ZZZ' gives '   105'
	  -105.000 passed through a mask of '-Z,ZZZ' gives '  -105'
	
	(    Acts like - but prints a (
	   105.000 passed through a mask of '(ZZZ)' gives ' 105 '
	    -5.000 passed through a mask of '(ZZZ)' gives '  (5)'
	
	+    Floats a + or - infront of the number depending on its sign
	     5.000 passed through a mask of '+ZZZ' gives '  +5'
	    -5.000 passed through a mask of '+ZZZ' gives '  -5'
	
	*    Fills all lead spaces to its right
	   104.100 passed through a mask of '*ZZZ,ZZZ.99' gives '*****104.10'
	   104.100 passed through a mask of '*$ZZZ,ZZZ.99' gives '*****$104.10'
	
	Any overflow is returned by picture as a double precision number.
	 -1234.000 passed through a mask of '(ZZZ)' gives '(234)'
	    With an overflow of -1.0
	   123.400 passed through a mask of '99' gives '23'
	    With an overflow of 1.0
	  1200.000 passed through a mask of 'ZZ' gives '00'
	    With an overflow of 12.0

qsort(data, n, size, comp) char *data; int n, size, (*comp)();
	Is your qsort() strangely slow. There are pathological cases
	which cause qsort to act badly. Example: 1000 items whose
	keys are all 7 and 8; a large array split into two halves
	both of which are already in order. This qsort() detects
	pathological conditions and adjusts.

long randl()
	Returns a long random number uniformly distributed in
	1..2147483562. This comes from CACM V. 31 N 6. And is
	the best algorithm I know as of this writing.
	see srandl() in this section.

char * replace(s1, pat, s3, all, matcher) char *s1, *pat, *s3, (matcher)();
	Replaces one or all occurances of pat in s1 by s3 and
	returns the result. The definition of match is set by matcher.
	This calls the user defined function matcher(sw, pat, &fin). The
	matcher must return the address of the pattern match and
	it's end in &fin. match() is a valid example of matcher.
	It replaces the first occurance, or all occurances of the
	pattern and returns the new pattern. The new pattern has been
	alloc()ed (see alloc).

showflag(data, flags, output) long data; char *flags, *output;
	Turns the bits in data to the flags in flags or '-'
	in the string output which must be as long as flags.

char * skip(s1, matcher, fin) char *s1, **fin; int (*matcher)();
	Skip one or more characters not matching some criterion
	such as isdigit(). Returns the first character skipped
	points fin at the character after the skip.

char * span(s1, matcher, fin) char *s1, **fin; int (*matcher)();
	Span one or more characters matching some criterion
	such as isdigit(). Returns the first character spanned
	points fin at the character after the span.

srandl(seed1, seed2) long seed1, seed2;
	randl() needs two seeds this sets them. Used only
	if you need to repeat a random number sequence.

strchtr(from, to, c, def) char *from, *to; int c, def;
	Look up the char c on the string from, return the corresponding
	char on the string to if it is found otherwise return the char
	def. example: strchr("ab", "xy", c, d); if c == 'a' return
	'x', if c == 'b' return 'y' otherwise return 'd'.
	
strcmpl(s1, s2)
	Case insensative string compare.

#define strlcpy(to, from) memcpy(to, from, sizeof(to))

ucase(s) char *s;
	Convert a string to upper case.

char * trim(s) char *s;
	Remove trailing whitespace from string s.

usage(s) char *s;
	Put out a usage: message and exit(1)

xdump(p, length) char *p;
	Make a vertical hex dump of p for length on stdout. This
	is a usefull debugging tool. Vertical hex prints as 3 lines
	The top line is the display character or . if it's not
	cleanly displayable. The next two lines are the hex digit.
	The data is blocked in groups of four bytes.

xopen(filename, acs)
	Like fopen() but it calls fatal() if the open fails.

yn(question, ...) char *question;
	Ask a question with any trailing parms printf style and
	get a y or n answer. Returns a 1 for 'Y' or 'y' a 0
	for 'n' or 'N', reasks otherwise.

The following are part of a user virtual memory system for
Coherent. Sometimes users port programs such as compress to
Coherent which have a small number of very large arrays. Since
Coherent is a small model operating system changes need to be
made. The following functions are intended to expedite these
changes.

void vinit(filename, ram) char *filename; unsigned ram;
	Init the virtual system using filename for work
	this may be a raw device such as /dev/rram1. ram
	is the amount of buffer space to give the system
	the more the better.

void vshutdown()
	Shut the virtual system, and make it restartable.

unsigned vopen(amt) unsigned long amt;
	Set up a virtual object. Say you want to emulate having
	a 100000 byte array and a 50000 byte array. use
	vid1 = vopen(100000L); vid2 = vopen(50000L);
	This does some checking and tells the system that any
	reference to vid2 will be between 100000 and 150000
	on the virtual file.

char *vfind(vid, disp, dirty) unsigned vid, dirty; unsigned long disp;
	Find a character on the virtual system mark the blocks
	dirty bit if the access is to write. Given the example in
	vopen, if you want to find the 1000 th byte in vdi1
	c = vfind(vdi1, 1000L, 0);
	To change the 2000 th byte in vid2 to d.
	*(vfind(vid2, 2000L, 1)) = d;
	Note the dirty indicator tells the system of the change so
	that the block will be written back before it is read over.
	Blocks are 512 bytes long so int's or long's can be read
	or written without multiple accesses to vfind.
@


1.1
log
@Initial revision
@
text
@d16 1
a16 1
	Malloc() n bytes and zero them, or put out a fatal error message.
d56 1
d63 1
a63 1
	all other \ sequences are errors.
d65 7
d93 1
a93 1
	Exchanges s1 and s2 for len.
d145 1
a145 1
	-    Floats a - infront of negitive numbers
d213 2
a214 2
	def. example: strchr("abc", "xyz", c, d); if c == 'a' return
	'x', if c == 'b' return 'y' if c > 'c' return d.
a215 1

d224 3
d230 15
a279 15

xdump(p, length) char *p;
	Make a vertical hex dump of p for length on stdout. This
	is a usefull debugging tool. Vertical hex prints as 3 lines
	The top line is the display character or . if it's not
	cleanly displayable. The next two lines are the hex digit.
	The data is blocked in groups of four bytes.

xopen(filename, acs)
	Like fopen() but it calls fatal() if the open fails.

yn(question, ...) char *question;
	Ask a question with any trailing parms printf style and
	get a y or n answer. Returns a 1 for 'Y' or 'y' a 0
	for 'n' or 'N', reasks otherwise.
@
