COHERENT manpages
This page displays the COHERENT manpage for libmisc [Library of miscellaneous functions].
List of available manpages
Index
libmisc -- Library
Library of miscellaneous functions
libmisc is a library of miscellaneous C functions. These functions perform
such useful tasks as handling such programming tasks as allocation of
memory, copying strings, displaying variables from C with COBOL-like
``picture'' descriptions, and supporting virtual arrays via secondary
storage.
Source code for libmisc is kept in the compressed tar archive
/usr/src/misc.tar.Z. To extract the files into a new subdirectory called
misc, type the command:
zcat /usr/src/misc.tar.Z | tar xvf -
To build the library, type the following:
cd misc
make
This compiles the libmisc routines and builds the library libmisc.a.
Archive misc.tar also includes the header file misc.h which protypes these
functions, and declares the global variables and constants they use. You
must include this header file in any program that uses any of the libmisc
functions.
Functions
The following summarizes the functions in libmisc.a:
char * alloc(n) unsigned n;
malloc() n bytes and initialize them to zero. Abort on failure.
int approx(a, b) double a, b;
If a and b are within epsilon, return one; otherwise, return zero.
epsilon is a visable double.
char *ask(reply, msg, ...) char *reply, *msg;
Print a message and retrieve the user's reply. msg is a printf()-
style format string that formats the text pointed to by any trailing
arguments. ask() constructs the prompt message from msg and prints it
on the standard output; then reads a line from stdin, stores it in the
place pointed to by reply, and returns its address. reply must point
to enough space to hold the user's reply.
For example,
sscanf(ask(buff, "%d numbers", 3), &a, &b, &c);
prints the message
Enter: 3 numbers
writes the user's reply into buff, and hands its address to sscanf().
void banner(word, pad) char *word; int pad;
Print word on stdout as a banner, preceded by pad spaces. Each letter
of the banner is fashioned from many occurrences of itself. This is
especially useful if you wish your listings to look like truly
professional, mainframe printouts.
bedaemon()
bedaemon() turns the calling program into a daemon. A daemon is a
process that executes in the background, without the usual connections
to standard I/O streams and terminals. Examples are cron and uuxqt.
To ensure proper operation in connection with other system software,
any program that you intend to run as a daemon should call bedaemon()
as its first step. This call closes all inherited, open-file
descriptors, detaches the process from its inherited process group and
controlling terminal, sets current directory to `/', and sets umask to
zero. For further information on daemon processes, see Unix Network
Programming by W. Richard Stevens (Englewood Cliffs, NJ, Prentice-Hall
Inc, 1990), §2.6.
unsigned short crc16(p) char *p;
Compute the 16-bit cyclic redundency check (crc16) of the string
pointed to by p, and return it. This function is very useful for
building hash tables or checking differences between strings.
void fatal(msg, ...) char *msg;
Print an error message and call exit(1). msg is a printf()-style
format string; trailing arguments must to point to data.
char *getline(ifp, lineno) FILE *ifp; int *lineno;
Get a line from the input file pointed to by ifp. This function
returns the address of the line, or NULL to indicate the end of file.
getline() calls malloc() to acquire space for the line, and allows
lines to be continued with a \-whitespace. It also implements lineno.
getline() recognizes the following escape sequences:
# to end of line is passed
\ whitespace through end of line is passed
\n newline
\p literal `#'
\a alarm
\b backspace
\r carrage return
\f form feed
\t tab
\\ backslash
\ddd octal number
All other \ sequences are errors that getline() reports on stderr.
tm_t *jday_to_tm(jd) jday_t jd;
Turn a Julian date to tm (time) structure. The Julian date is the
number of days since the beginning of the Julian calendar, January 1,
4713 B.C.; it is a good way to store dates in a system-independent
manner, such as in a data base. Structure jday_t is defined in
misc.h. Structure tm is defined in <time.h>.
time_t jday_to_time(jd) jday_t jd;
Turn Julian date structure to COHERENT time. Type time_t is defined
in header file <sys/types.h>.
void splitter(ofp, line, limit) FILE *ofp; char *line; int limit;
Write line into file ofp, splitting it into chunks less than limit
bytes long. splitter() inserts a \ between chunks, and attempts to do
this on white-space boundaries. splitter() produces a long line
rather than split on non-whitespace. If line does not end in a
newline, splitter() adds one. This is the inverse of getline().
int is_fs(special) char *special;
Check whether special names 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.
is_fs() returns -1 if special is not a device, or if open(), read(),
or seek() fails. It returns zero if no file system was found, or one
if special names a legal file system.
char *lcase(st) char *str;
Convert every character in str to lower case. Note that this works
only with the U.S. dialect of English; it does not work with German or
other languages that use characters in the upper half of the ASCII
table.
char *match(string, pattern, fin) char *string, *pattern, **fin;
match() resembles pnmatch(), except that it 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.
char *metaphone(word) char *word;
Translate word into a short phonetic equivalent for easy lookup. It
resembles Knuth's soundex method, except that it uses a superior
algorithm.
char *newcpy(str) char *str;
Create a NUL-terminated copy of str and return its address. Call
fatal() if there is no space.
char *pathn(name, envpath, deflpath, access)
char *name, *envpath, *deflpath, *access;
pathn() looks for file name. It searches the directories named in the
environmental variable envpath. If the user has not set envpath, or if
it is NULL, pathn() searches the default path deflpath. name must have
access permission. pathn() returns the full path to the file found.
For example:
pathn("helpfile", "LIBPATH", "/lib", "r")
searches the directories named in LIBPATH for file helpfile, for which
the user must have read permission. If LIBPATH is not set, pathn()
searches /lib for helpfile.
#include <regexp.h>
regexp *regcomp(exp) char *exp;
int regexec(prog, string) regexp *prog; char *string;
regsub(prog, source, dest) regexp *prog; char *source; char *dest;
regerror(msg) char *msg;
These functions implement a standard method for parsing regular
expressions. regcomp() turns a regular expression into a structure of
type regexp and returns a pointer to it. regexec() matches string
against the regular expression in prog. It returns one if string
matches exp, and zero if it does not. regsub() copies source to dest,
and makes substitutions according to the most recent regexec()
performed using prog. regerror() is called whenever an error is
detected in regcomp(), regexec(), or regsub(). See regexp.doc for
details.
long randl()
Return a long random number uniformly distributed between 1 and
2,147,483,562. This comes from Communications of the ACM, volume 31,
number 6. See srandl(), below.
char *replace(s1, pat, s3, all, matcher) char *s1, *pat, *s3, (matcher)();
Replace one or all occurrences of pat in string s1 by s3, and return
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 its end
in &fin. match() is a valid example of matcher. It replaces the
first occurrence, or all occurrences of the pattern, and returns the
new pattern. The new pattern has been alloc()'d.
showflag(data, flags, output) long data; char *flags, *output;
Turn 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 all initial characters in string s1 that fail when examined
matcher. matcher is usually a character function, e.g., isdigit(). It
returns the first character skipped. skip() points fin at the
character after the skip.
char *span(s1, matcher, fin) char *s1, **fin; int (*matcher)();
Span all initial characters in string s1 that match when examined by
matcher. matcher is usually a character function, e.g., isdigit(). It
returns the first character spanned. span() points fin at the
character after the span.
srandl(seed1, seed2) long seed1, seed2;
randl() needs two seeds; srandl() sets them. Use it only if you need
to repeat a random-number sequence.
strchtr(from, to, c, def)
char *from, *to; int c, def;
Look up the character c in the string from. Return the corresponding
character in the string to if it is found; otherwise, return the
default character def.
For example, consider the call:
strchtr("ab", "xy", c, d);
If variable c equals `a', then strchtr() returns `x'; if c equals `b',
then it returns `y'; otherwise, it returns the value of d
strcmpl(s1, s2)
Case-insensitive string comparison. Resembles strcmp().
jday_t time_to_jday(time) time_t time;
Turn COHERENT time to Julian date structure. The Julian date is the
number of days since the beginning of the Julian calendar, January 1,
4713 B.C. The structure jday_t is defined in misc.h. Type time_t is
defined in <sys/types.h>.
jday_t tm_to_jday(tm) tm_t *tm;
Turn the time structure tm date into Julian date structure. Structure
tm is defined in <time.h>.
char *trim(s) char *s;
Remove trailing whitespace from string s.
ucase(s) char *s;
Convert a string to upper case.
usage(s) char *s;
Print string s and call exit(1).
xdump(p, length) char *p;
Print on stdout a vertical hexadecimal dump of string p.
A vertical hexadecimal dump prints as three lines. The top line is
the display character, or `.' if the character cannot be displayed
cleanly. The next two lines are the hexadecimal numerals. The data
are blocked into groups of four bytes.
xopen(filename, acs) char *filename, *acs;
Like fopen(), but call fatal() if the open fails.
yn(question, ...) char *question;
Ask a question and retrieve a `Y' or `N' answer. question is a
printf()-style format string; any trailing parameters should point to
data used in question. yn() returns one if the user answers `Y' or
`y', and returns zero if she answers `N' or `n'.
Virtual Memory
The following functions are part of a virtual memory system for COHERENT
286. Occasionally, users port programs like compress to COHERENT 286 that
use a small number of very large arrays. Because COHERENT 286 is a SMALL-
model operating system, special provision must be made for arrays too large
to fit into a 64-kilobyte data segment. The following functions enable
programs that are to be run under COHERENT 286 use very large arrays:
void vinit(filename, ram) char *filename; unsigned ram;
Initialize the virtual-memory system, using filename for work.
filename 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-memory system, and make it restartable.
unsigned vopen(amt) unsigned long amt;
Set up a virtual-memory object. For example, if you want to emulate
having a 100,000-byte array and a 50,000-byte array, use the call
vid1 = vopen(100000L); vid2 = vopen(50000L);
This does some checking and tells the system that any reference to
vid2 will be between 100,000 and 150,000 in the virtual file.
char *vfind(vid, disp, dirty)
unsigned vid, dirty; unsigned long disp;
Find a character in the virtual system, mark the block's dirty bit if
the access is to write. Given the example in vopen(), if you want to
find the 1,000th byte in vdi1, use the call:
c = *(vfind(vdi1, 1000L, 0));
To change the 2000th byte in vid2 d, use the call
*(vfind(vid2, 2000L, 1)) = d;
Note that 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().
File Locking
libmisc holds a number of routines with which you can lock and unlock files
and devices. It is adapted from the mechanism used by the COHERENT
implementation of UUCP.
Lock files are created in $SPOOLDIR. A lock file is given the name
LCK..resource. It contains a decimal representation of the process
identifier (pid) of the process that created the lock.
You can provide an alternate pid by using one of the `n' routines -- i.e.,
locknrm(), lockntty(), and unlockntty(). The unlocking routines regard a
pid of zero as an override -- they remove the lock regardless of which
process created the lock.
For a tty device, resource is a string that consists of a decimal
representation of its major number, a decimal point, and the lower five
bits of its minor number.
Each routine takes a string that names the resource to lock or unlock. The
``tty'' routines (i.e., lockntty(), locktty(), unlockntty(), and
unlocktty()) want the base name of the tty to be locked (without the /dev/
part).
Every lock routine returns zero on failure and one on success.
lockit(resource) char *resource;
Use a resource string to lock a tty.
lockexist(resource) char *resource;
Check whether a lock file exists for the tty with resource.
locknrm(resource, pid) char *resource; int pid;
Remove a lock file for a tty owned by process pid.
lockntty(tty, pid) char *tty; int pid;
Lock a tty for process pid.
lockrm(resource) char *resource;
Remove a lock file for tty with resource.
locktty(tty) char *tty;
Lock a tty.
lockttyexist(tty) char *tty;
Check whether a given tty is locked.
unlockntty(tty, pid) char *tty; int pid;
Unlock a tty for process pid. Unlocking always succeeds.
unlocktty(tty) char *tty;
Unlock a tty that the current process owns.
unlockit(resource, pid) char *resource; int pid;
Unlock something for process pid.
Templates and Pictures
libmisc includes a function, picture(), for formatting numeric strings. It
has the following syntax:
double picture(dble, format, output)
double dble; char *format, *output;
picture() performs numeric formatting under C. It resembles masking
functions built into COBOL and BASIC, but is superior to either. dble
gives the number to format; format gives the format mask; and output points
to the area into which the formatted number is written. output must be at
least as large as format. If dble overflows the picture, picture() returns
the overflow.
The following summarizes the values that can appear in the format string.
Note that throughout, the symbol <sp> indicates a space character,
not the literal string ``<sp>''.
9 Provide a slot for a number. Passing 5.000 through a mask of 999 CR
gives ``005''. Passing -5.000 through a mask of 999 CR yields ``005
CR''. Note that picture() does not recognize the characters `C' and `R'
as being special. Trailing non-special characters print only if the
number is negative.
Z Provide a slot for a number, but suppress leading zeroes. For example,
passing 1034.000 through a mask of ZZZ,ZZZ gives
``<sp><sp>1,034''. Note that picture() does not recognize a
comma as being a special character. picture() prints embedded non-
special characters only if they are preceeded by significant digits.
J Provide a slot for a number, but shrink out leading zeros. For example,
passing 1034.000 through a mask of JJJ,JJJ yields ``1,034''.
K Provide a slot for a number, but shrink out any zeros. For example,
passing 70884.000 through a mask of K9/K9/K9 yields ``7/8/84''.
$ Float a dollar sign to the left of the displayed number. For example,
passing 105.000 through a mask of $ZZZ,ZZZ yields
``<sp><sp><sp><sp>$105''.
. Separate the number between decimal and integer portions. For example,
passing 105.670 through a mask of Z,ZZZ.999 yields
``<sp><sp>105.670''.
T Provide a slot for a number, but suppress trailing zeroes. For example,
passing 105.670 through a mask of Z,ZZ9.9TT yields
``<sp><sp>105.67<sp>''.
S Provide a slot for a number, but shrink out trailing zeroes. For
example, passing 105.670 through a mask of Z,ZZ9.9SS yields
``<sp><sp>105.67''.
- Float a negative sign in front of negitive numbers. For example,
passing 105.000 through a mask of -Z,ZZZ yields
``<sp><sp><sp<105'', whereas passing -105.000 through
a mask of -Z,ZZZ yields ``<sp><sp>-105''.
( Acts like -, but prints a parenthesis. For example, passing 105.000
through a mask of (ZZZ) yields ``<sp>105<sp>'', whereas
passing -5.000 through a mask of (ZZZ) yields
``<sp><sp>(5)''.
+ Float a + or - in front of the number, depending on its sign. For
example, pasing 5.000 through a mask of +ZZZ yields
``<sp><sp>+5'', whereas passing -5.000 through a mask of
+ZZZ yields ``<sp><sp>-5''.
* Fill all spaces to right with asterisks. For example, passing 104.100
through a mask of *ZZZ,ZZZ.99 yields ``*****104.10''; whereas passing
104.100 through a mask of *$ZZZ,ZZZ.99 yields ``*****$104.10''.
picture() returns any overflow as a double. For example, passing
-1234.000 through a mask of (ZZZ) yields ``(234)'' with an overflow of
-1.0; passing 123.400 through a mask of 99 yields ``23'' with an
overflow of 1.0; and passing 1200.000 through a mask of ZZ yields ``00''
with an overflow of 12.0.
Files
/usr/src/misc.tar.Z -- Compressed tar archive of sources
See Also
libraries,
tar,
zcat
Notes
The misc library is provided on an as-is basis only. Caveat utilitor!
