root@stag.UUCP (Computer Abuser) (07/26/87)
----------------------Cut Here...Start of Part 2 of 2------------------------
FORMATTING/TYPE CONVERSION:
_printf(op, put, fmt, args)
char *op;
int (*put)();
char *fmt;
int *args;
<fmt> points to a format control string. <args> pointers to a
list of arguments. The format string is used to create and output
stream with the arguments. The <put> function is used to output
each character. The <op> parameter is given to the <put> function
to specify the output stream. Calls to <put> are of the form:
"(*put)(c, op);" where <c> is the character to output. The format
string is composed of characters and format specifications. The
'%' character introduces a format specifier. The general form of
a format specifier is:
%[-][ |+][0][<width>|*][l]{d|i|u|o|x|b|c|s}
The '-' specifies left justification. The ' ' or '+' specifies
the character which preceeds positive numeric values. The '0'
specifies that numeric fields will be padded with '0' rather than
' '. The <width> field is a numeric value specifying a fixed
field width. If '*' is specified for the field width, an "int"
value from the argument list is taken to contain the field width.
If output exceeds the field width, the field will be '*' filled.
The "<min>.<max>" type of width specification is not supported.
The <width> field simply acts like "<width>.<width>", specifying
both minimum and maximum field size with one value. In order
to be somewhat compatible with the dotted width spec, the width
value will be zeroed if a '.' is seen, allowing the digits of
the second field spec to set the width value. If no width is
specified, the field width varies according to the data printed.
The 'l' specifies that the associated value is a "long" type.
The trailing character specifies the format type, as follows:
d Signed decimal integer
i same as 'd'
u Unsigned decimal integer
o Unsigned octal integer
x Unsigned hexadecimal integer
b Unsigned binary integer
c Character
s String
If the character following the '%' is not recognized, it is
simply passed along to the output stream, thus "%%" is used to
print a single '%' character.
char *ltoa(n, buffer, radix)
long n;
char *buffer;
int radix;
Convert the long value <n> to a string in <buf> using <radix>
as the number base. If <n> is negative, '-' will be the first
character in <buf>. A pointer to <buf> is returned.
char *ultoa(n, buffer, radix)
unsigned long n;
char *buffer;
int radix;
Convert the unsigned long value <n> to a string in <buf> using
<radix> as the number base. A pointer to <buf> is returned.
char *itoa(n, buffer, radix)
int n;
char *buffer;
int radix;
Convert the integer value <n> to a string in <buf> using <radix>
as the number base. If <n> is negative, '-' will be the first
character in <buf>. A pointer to <buf> is returned.
long ltoa(number)
char *number;
Convert the string <number> to a long value. Leading whitespace
is ignored, a leading +/- is optional. Characters are processed
until a non-digit is reached. Return value is undefined in an
overflow situation.
int itoa(number)
char *number;
Convert the string <number> to an int value. Leading whitespace
is ignored, a leading +/- is optional. Characters are processed
until a non-digit is reached. Return value is undefined in an
overflow situation.
_scanf(ip, get, unget, fmt, args)
char *ip;
int (*get)();
int (*unget)();
char *fmt;
char **args;
<fmt> points to a format control string. <args> pointers to a
list of arguments, each of which is the address of a variable in
which input data may be stored. The format string is used to
control reading of characters from the <get> function. As each
character is needed <get> is called in the form: "c = (*get)(ip);"
where <c> is the character read (negative for errors) and <ip>
is the auxiliary pointer specified by the <ip> parameter. If
a character needs to be un-gotten, a call to <unget> of the form:
"(*unget)(c, ip);" is made. The format string is composed of
characters and format specifications. Any characters in <fmt>,
except whitespace characters, which are not part of a format
specifier are expected to be matched one-to-one by characters in
the input stream. Scanning terminates if a mismatch occurs or
if any call to <get> results in an error. Whitespace characters
match 0 or more whitespace characters in the input stream. The
'%' character introduces a format specifier. The general form
of a format specifier is:
%[*][<width>][l]{d|i|u|o|x|b|c|s}
The '*' specifies that a field is to be scanned by not stored. No
variable pointer should be provided for non-stored format specs.
The <width> field specifies that maximum number of characters to
be process to fill the given format type. Less than <width>
characters will be processed if the field ends before <width>
characters have been processed. A field ends when either a
whitespace character, or a character which does not fit the
specified format, is read. The 'l' specifies that the associated
variable is a "long" type. The trailing character specifies the
format type, as follows:
d Signed decimal integer
u Unsigned decimal integer
o Unsigned octal integer
x Unsigned hexadecimal integer
b Unsigned binary integer
i Unsigned decimal/octal/hexadecimal/binary integer
c Character
s String
If a <width> is specified with the 'c' format, exactly <width>
characters (including whitespace) are read from the input
stream, and written to a string. No '\0' character is added.
If the character following the '%' is not recognized, it is
expected to match the input stream as a non-format character,
thus "%%" is used to match a single '%' character.
char *ctlcnv(string)
char *string;
Convert \<char> notation in <string> to actual characters. This
is useful for reading strings from a stream when you want to allow
insertion of control character or other characters that may have
special meaning otherwise, or may not otherwise be allowed. The
following formats are supported:
\n newline or linefeed
\r carriage return
\0 null character (value 0)
\b backspace
\t horizontal tab
\v vertical tab
\f form feed
\a alarm (bell)
\\ backslash
\' single quote
\" double quote
\NNN octal constant
\xNN hexadecimal constant
\<nl> "folded" line (both characters removed)
A pointer to the modified <string> is returned.
STRING MANIPULATION:
You may want to include "STRING.H" in your program if you use
functions in this section, otherwise you'll have to declare the
return types for any functions you use.
char *blkcpy(dest, source, len)
char *dest;
char *source;
int len;
Copies the <source> block to the <dest>. <len> bytes are
always copied. No terminator is added to <dest>. A pointer
to <dest> is returned. Overlap checking IS done.
char *blkfill(dest, data, len)
char *dest;
char data;
int len;
Fill <dest> will <len> bytes of <data>. A pointer to <dest>
is returned.
int blkcmp(blk1, blk2, len)
char *blk1;
char *blk2;
int len;
Lexicographically compare the two blocks. Return a value
indicating the relationship between the blocks. Possible
return values are:
negative blk1 < blk2
0 blk1 == blk2
positive blk1 > blk2
<len> bytes are always compared.
int blkicmp(blk1, blk2, len)
char *blk1;
char *blk2;
int len;
Compare blocks as with blkcmp(), but ignore the case of any
alphabetic characters.
char *memcpy(dst, src, cnt)
char *dst;
char *src;
int cnt;
Same as blkcpy().
char *memccpy(dst, src, c, cnt)
char *dst;
char *src;
char c;
int cnt;
Copy bytes from <src> to <dst> until either <cnt> bytes have been
copied, or the character <c> has been copied. Returns <dst>.
char *memset(dst, c, cnt)
char *dst;
char c;
int cnt;
Same as blkfill().
char *memchr(buf, c, cnt)
char *buf;
char c;
int cnt;
Search the first <cnt> bytes of <buf> for <c>. Returns a pointer to
the matching character, or NULL if not found.
int memcmp(buf1, buf2, cnt)
char *buf1;
char *buf2;
int cnt;
Same as blkcmp().
int memicmp(buf1, buf2, cnt)
char *buf1;
char *buf2;
int cnt;
Same as blkicmp().
int strlen(string)
char *string;
Returns the number of characters in a string, not including the
terminating '\0'.
char *strcpy(dest, source)
char *dest;
char *source;
Copies the <source> string to the <dest> including the '\0'. A
pointer to the start of <dest> is returned.
char *strncpy(dest, source, limit)
char *dest;
char *source;
int limit;
Copies the <source> string to the <dest>. At most, <limit>
characters are copied. If <source> ends before <limit> characters
have been copied, the '\0' is copied, otherwise <dest> is not
terminated by the copy.
char *strdup(string)
char *string;
Create a copy of <string> and return a pointer to the copy.
char *strset(string, c)
char *string;
char c;
Fill <string> with <c> up the the terminating '\0' of <string>.
char *strnset(string, c, n)
char *string;
char c;
int n;
Fill at most <n> characters of <string> with <c>, up the the
terminating '\0' of <string>.
char *substr(dest, source, start, end)
char *dest;
char *source;
int start;
int end;
Copy characters from <source> to <dest> starting with character
<start> and ending with <end>. A pointer to <dest>, which will
be '\0' terminated, is returned.
char *subnstr(dest, source, start, length)
char *dest;
char *source;
int start;
int length;
Copy <length> characters from <source> to <dest> starting with
character <start>. A pointer to <dest>, which will be '\0'
terminated, is returned.
char *strcat(dest, source)
char *dest;
char *source;
Concatenate <source> on the end of <dest>. The terminator of
<dest> will be overwritten by the first character of <source>.
The termintor from <source> will be copied. A pointer to
the modified <dest> is returned.
char *strncat(dest, source, limit)
char *dest;
char *source;
int limit;
Concatenate <limit> characters from <source> onto <dest>. If
<source> contains less than <limit> characters, the length of
source is used for <limit>. The terminating '\0' is always
added. A pointer to <dest> is returned.
char *strupr(string)
char *string;
Convert all alphabetic characters in <string> to upper case.
char *strlwr(string)
char *string;
Convert all alphabetic characters in <string> to lower case.
char *strrev(string)
char *string;
Reverse the order of the characters in <string> in place.
int strcmp(str1, str2)
char *str1;
char *str2;
Lexicographically compare the two strings. Return a value
indicating the relationship between the strings. Possible
return values are:
negative str1 < str2
0 str1 == str2
positive str1 > str2
int strncmp(str1, str2, limit)
char *str1;
char *str2;
int limit;
Compare strings as with strcmp(), but limit comparison to the
<limit> characters.
int stricmp(str1, str2)
char *str1;
char *str2;
Compare strings as with strcmp(), but ignore the case of any
alphabetic characters.
int strnicmp(str1, str2, limit)
char *str1;
char *str2;
int limit;
Compare strings as with strncmp(), but ignore the case of any
alphabetic characters.
char *strstr(string, pattern)
char *string;
char *pattern;
Return a pointer to the first occurance of <pattern> in <string>.
NULL is returned if <pattern> is not found.
char *stristr(string, pattern)
char *string;
char *pattern;
Same as strstr(), but ignore the case of any alphabetic characters.
char *strchr(string, symbol)
char *string;
char symbol;
Return a pointer to the first occurance of <symbol> in <string>.
NULL is returned if <symbol> is not found.
char *strrchr(string, symbol)
char *string;
char symbol;
Return a pointer to the last occurance of <symbol> in <string>.
NULL is returned if <symbol> is not found.
int strpos(string, symbol)
char *string;
char symbol;
Return the index of the first occurance of <symbol> in <string>.
-1 is returned if <symbol> is not found.
int strrpos(string, symbol)
char *string;
char symbol;
Return the index of the last occurance of <symbol> in <string>.
-1 is returned if <symbol> is not found.
int strspn(string, set)
char *string;
char *set;
Return the length of the sub-string of <string> that consists
entirely of characters found in <set>. The terminating '\0'
in <set> is not considered part of the match set. If the first
character if <string> is not in <set>, 0 is returned.
int strcspn(string, symbol)
char *string;
char *set;
Return the length of the sub-string of <string> that consists
entirely of characters not found in <set>. The terminating '\0'
in <set> is not considered part of the match set. If the first
character if <string> is in <set>, 0 is returned.
char *strpbrk(string, set)
char *string;
char *set;
Return a pointer to the first occurace in <string> of any
character in <set>.
char *strrpbrk(string, set)
char *string;
char *set;
Return a pointer to the last occurace in <string> of any
character in <set>.
char *strtok(string, delim)
char *string;
char *delim;
Return a token from <string>. If <string> is not NULL, it is
the beginning of a string from which tokens are to be extracted.
Characters found in <delim> are skipped over to find the start
of a token, characters are then accumulated until a character in
<delim> is found, or the terminator of <string> is reached.
A pointer to the '\0' terminated token is then returned. Note
that this function modifies <string> (by inserting '\0's) in
the process. Subsequent calls to strtok() may specify NULL as
the <string> argument, in which case subsequent tokens are
returned, or NULL if there are no more tokens.
char *strtrim(string, junk)
char *string;
char *junk;
Remove leading and trailing characters found in <junk>
from <string>. Return a pointer to the modified <string>.
char *stradj(string, dir)
char *string;
int dir;
Adjust <string> by adding space if <dir> is positive, or removing
space if <dir> is negative. The magnitude of <dir> is the number
of character positions to add or remove. Characters are added or
removed at the beginning of <string>. A pointer to the modified
<string> is returned.
int strrpl(string, ptrn, rpl, n)
char *string;
char *ptrn;
char *rpl;
int n;
Replace at most <n> occurances of <ptrn> in <string> with <rpl>.
If <n> is -1, replace all. Return the number of replacments.
int strirpl(string, ptrn, rpl, n)
char *string;
char *ptrn;
char *rpl;
int n;
Same as strrpl() except ignore the case of alphabetic characters.
CHARACTER FUNCTIONS:
To use the functions in this section, you must include "CTYPE.H"
in your source file. Please note that the isXXXX() functions,
except isascii(), only have defined results if isascii() is true.
(ie. they only work properly on values 0x00 through 0x7F)
int toupper(c)
int c;
Convert <c> to upper case, if alphabetic. This is implemeted
as a macro and also as a function. You may force use of the
function version rather than the macro (which evaluates its
argument twice) by using the "#undef toupper" directive.
int tolower(c)
int c;
Convert <c> to lower case, if alphabetic. This is implemeted
as a macro and also as a function. You may force use of the
function version rather than the macro (which evaluates its
argument twice) by using the "#undef tolower" directive.
int _toupper(c)
int c;
This macro should be used only if <c> is known to be lower case.
It converts <c> to upper case. Results are undefined if converting
a character which is not lower case.
int _tolower(c)
int c;
This macro should be used only if <c> is known to be upper case.
It converts <c> to lower case. Results are undefined if converting
a character which is not upper case.
int toascii(c)
int c;
Convert <c> to 7-bit ascii, putting it into the range 0x00..0x7F.
int isalnum(c)
int c;
Return non-zero if <c> is '0'..'9','A'..'Z','a'..'z'.
int isalpha(c)
int c;
Return non-zero if <c> is 'A'..'Z','a'..'z'.
int isascii(c)
int c;
Return non-zero if <c> is 0x00..0x7F.
int iscntrl(c)
int c;
Return non-zero if <c> is 0x00..0x1F,0x7F.
int isdigit(c)
int c;
Return non-zero if <c> is '0'..'9'.
int islower(c)
int c;
Return non-zero if <c> is 'a'..'z'.
int isprint(c)
int c;
Return non-zero if <c> is 0x20..0x7E.
int ispunct(c)
int c;
Return non-zero if <c> is not iscntrl(), isalnum() or isspace().
int isspace(c)
int c;
Return non-zero if <c> is 0x09..0x0D,0x20.
int isupper(c)
int c;
Return non-zero if <c> is 'A'..'Z'.
int isxdigit(c)
int c;
Return non-zero if <c> is '0'..'9','A'..'F','a'..'f'.
DATE/TIME FUNCTIONS:
To use the functions in this section, you must include "TIME.H"
in your source file.
long time(rawtime)
long *rawtime;
Get the current system clock date/time value. Under many systems,
this function returns the number of seconds since 00:00:00 GMT on
Jan 1, 1970. This implementation returns an encoded date/time
value instead. Therefore any programs which depend on this value
being a number of seconds will not work properly. However, other
functions in this section which make use of the raw time value
returned by time() are implemented to be compatible with this
encoding, and will work properly. In addition to returning the
raw time value, if the <rawtime> pointer in not NULL, the value
is stored in the long <rawtime> points to.
char *ctime(rawtime)
long *rawtime;
Convert <rawtime> to a string. A 26 character fixed field string
is created from the raw time value. The following is an example
of what this string might look like:
"Wed Jul 08 18:43:07 1987\n\0"
A 24-hour clock is used, and due to a limitation in the ST system
clock value, only a resolution of 2 seconds is possible. A pointer
to the formatted string, which is held in an internal buffer, is
returned.
struct tm *gmtime(rawtime)
long *rawtime;
Convert <rawtime> to fill time structure fields. A pointer to an
internal structure is returned. Refer to "TIME.H" for the values
of the various structure fields.
struct tm *localtime(rawtime)
long *rawtime;
Since there is not concept of "time zone" on the ST, this function
is identical to gmtime().
char *asctime(time)
struct tm *time;
Convert <time> structure value to a string. The same format, and
the same internal buffer, as for ctime() is used for this function.
long cnvtime(rawtime, time)
long *rawtime;
struct tm *time;
Convert <time> structure value to raw time format. In addition to
returning the raw time value, if the <rawtime> pointer in not NULL,
the value is stored in the long <rawtime> points to. (cf: time)
void stime(rawtime)
long *rawtime;
Set the system clock to <rawtime>.
int utime(pathname, rawtime)
char *pathname;
long *rawtime;
Set the modification date of <pathname> to <rawtime>. Returns zero
for success, or a negative error code.
long start_timer(t)
TIMER *t;
Start a 200Hz timer. This timer value can later be checked with
time_since() to determine elapsed time. These functions provide
a very low-overhead way of timing events.
long time_since(t)
TIMER *t;
Returns the number of 200Hz ticks since start_timer() was called
for timer <t>.
sleep(dt)
int dt;
Suspend operation for <dt> seconds. This is implemented as a
start_timer()/time_since() tight loop waiting for the specified
amount of time to pass. In a multi-tasking environment, this
function should be replaced by a call which will de-activate
this task for a period of time, allowing other tasks to run.
SEARCHING AND SORTING:
qsort(base, num, size, cmp)
char *base;
int num;
int size;
int (*cmp)();
Perform a recursive quick-sort on an array starting at <base>
containing <num> elements of <size> bytes each. The function
pointed to by <cmp> is used to compare elements. Pointers to
two items in the array are passed to the function, which must
return a number representing their relationship as follows:
negative item1 < item2
0 item1 == item2
positive item1 > item2
The qsort() function requires the use of a temporary data area
that is large enough to hold <size> bytes. The default space
provided is 128 bytes large. If your record size is larger than
128 bytes, YOU MUST provide an alternative storage area. The
global variable "_qbuf" points to the storage qsort() will use.
Setting "_qbuf" to NULL restores use of the internal buffer.
This routine is optimized to avoid N*N sort times for ordered data.
hsort(base, num, size, cmp)
char *base;
int num;
int size;
int (*cmp)();
Perform an N*log(N) heap-sort on an array starting at <base>
containing <num> elements of <size> bytes each. The function
pointed to by <cmp> is used to compare elements. Pointers to
two items in the array are passed to the function, which must
return a number representing their relationship as follows:
negative item1 < item2
0 item1 == item2
positive item1 > item2
The hsort() function requires no extra storage, is not recursive,
and has an almost constant N*log(N) sort time. In the average
case, it is about half as fast as qsort() on random data. If
portability is a concern, it should be noted that qsort() is
almost always available, but hsort() is not.
char *bsearch(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();
Perform a binary search for <key> on the sorted data at <base>.
<num>, <size> and <cmp> are like the corresponding parameters
to qsort(). A pointer to the matching element is returned for
success, or NULL for failure. The global variable "_bsearch"
will contain the index of either the matching element, or the
place where <key> value should be inserted. The use of "_bsearch"
is not supported by many implementations of bsearch().
char *lsearch(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();
Perform a linear search for <key> on the data at <base>. The
<num>, <size> and <cmp> parameters are like the corresponding
parameters to qsort(). A pointer to the first matching element
is returned for success, or NULL for failure. If <key> is not
found, it will be added to the end of the array.
char *lfind(key, base, num, size, cmp)
char *key;
char *base;
int num;
int size;
int (*cmp)();
Like lsearch(), but do not add elements which are not found.
MISCELLANEOUS FUNCTIONS:
int rand()
Return a pseudorandom number in the range 0..32767
void srand(seed)
unsigned int seed;
Seed the random number generator. This function is #defined as
a comment, since no seeding is possible for this implementation
of rand().
MACRO abs(x)
Return the absolute value of <x>. This macro evalutes it's
argument twice. ((x)<0?(-(x)):(x))
MACRO max(x,y)
Return the larger of <x> and <y>. This macro evaluates the
larger argument twice and the smaller argument once.
MACRO min(x,y)
Return the smaller of <x> and <y>. This macro evaluates the
smaller argument twice and the larger argument once.
MACRO swap(a,b)
Exchange <a> and <b> by chained XORs. The macro evaluates
each argument several times.
----- END OF FILE -----