libukcprog/doc/ukcprog.3

.\" $Id: ukcprog.3,v 1.18 1993/02/23 11:31:42 gjap Exp $ UKC
.\" .fX - print the argument in a fixed font
.de fX
\&\\$3\f(CR\\$1\fP\\$2
..
.\" .Vs - start example
.de Vs
.LP
.ne 1i
.RS
.nf
.ft CR
..
.\" .Ve - end example
.de Ve
.ft P
.fi
.hy 0
.RE
.LP
..
.TH UKCPROG 3  "February 1991" "UKC Local"
.SH NAME
ukcprog \- Library of utilities for C programmers
.SH SYNOPSIS
.nf
.LP
In source code,
.Vs
#include <ukcprog.h>
.Ve
and link with
.Vs
cc ... -lukcprog
.Ve
.SH AVAILABILITY
.LP
.\"
.\" The following sentence motivated the port to MS-DOG.
.\"
This is a UKC library, available for the \s-1UNIX\s0 and \s-1VMS\s0
operating systems, and for MS-DOS.
.\"
.\" It was worth it ...
.\"
The source code is freely available so if you want to make
a source release of your application you can include a copy of the
source of this library as well.
.SH DESCRIPTION
.LP
The ukcprog library contains generally useful low level routines.
The
.fX ukcprog.h
header file contains prototypes for the
routines as well as defining some useful macros and types.
.Vs
#ifdef __STDC__
#define PROTO(a)        a
typedef void *voidptr;
#else
#define PROTO(a)        ()
#define const
#define volatile
#define signed
typedef char *voidptr;
#endif
.Ve
.LP
The definitions of
.fX const ,
.fX volatile
and
.fX signed
allow these ANSI C keywords to be used in code which must be portable
to pre-ANSI C compilers.
.LP
The
.fX voidptr
typedef is similarly there to help with code for pre-ANSI compilers
which do not support the
.fX "void *" ' `
type.
Functions which are documented here as returning
.fX "void *" ' `
return
.fX "char *" ' `
when compiling with a non-ANSI C compiler.
.LP
The
.fX PROTO
macro is useful for declaring function prototypes
for use with ANSI C while still allowing the code to be compiled with
K&R compilers.
It is used thus:
.Vs
int myfunc PROTO((int arg1, char *arg2));
.Ve
With an ANSI C compiler this expands to
.Vs
int myfunc (int arg1, char *arg2);
.Ve
whereas a pre-ANSI compiler sees:
.Vs
int myfunc ();
.Ve
.LP
Note the double brackets; these are necessary to make all the parameters
a single argument to the
.fX PROTO
macro.
.Vs
#ifndef FALSE
#define FALSE   0
#endif
#ifndef TRUE
#define TRUE    1
#endif
#ifndef bool
#define bool int
#endif
.Ve
These define the commonly used
.fX TRUE
and
.fX FALSE
macros to their usual values.
The definitions are protected in case these are already defined.
The
.fX bool
macro is intended to be used to declared variables
that are conceptually boolean.
A
.fX #define
is used rather than a typedef because there might already be a typedef
for
.fX bool .
.Vs
#ifdef __STDC__
#define CAT(a,b)        a ## b
#else
#define _IDENT(a) a
#define CAT(a,b) _IDENT(a)b
#endif /* !__STDC__ */
.Ve
The
.fX CAT
macro can be used to glue two tokens together in the same way as
the ANSI C
.fX ##
operator.
.fX CAT
also works with many (but not all) pre-ANSI C preprocessors.
.Vs
void panic(const char *message)
.sp
typedef void (*panic_handler_t)(const char *message);
panic_handler_t install_panic_handler(panic_hander_t handler)
.Ve
By default
.fX panic()
produces a message on stderr of the form
.Vs
fatal internal error: \fIsomething\fP (aborting)...
.Ve
It then calls
.fX abort(3)
to produce a core dump.
Alternative `panic handlers' can be installed using
.fX install_panic_handler()
which returns the previous handler.
Panic handlers can perform tidy-up tasks, such as
removing temporary files or calling
.fX chdir(2)
to arrange for
the core to land in a safe place.
If a panic handler is called and returns then the default
action is carried out.
.Vs
void *e_malloc(size_t size)
void *e_realloc(void *old, size_t size)
char *strsave(const char *str)
.Ve
.fX e_malloc()
and
.fX e_realloc()
are error-checking versions
of the corresponding routines in the standard C library.
They call
.fX panic()
if the request fails.
.fX e_realloc()
behaves according to the ANSI specification for
.fX realloc() ;
that is, if
.fX old
is NULL it behaves like
.fX malloc()
and if size is 0, it behaves like
.fX free() .
.fX strsave()
allocates some memory using
.fX e_malloc() ,
copies
.fX str
into it, and returns a pointer to the copy.
.Vs
char *fpgetline(FILE *fp)
.Ve
.fX fpgetline()
reads characters from the standard IO stream
.fX fp
until a newline character or EOF is encountered.
.fX fpgetline()
returns
.fX NULL
if EOF or an error occurred before any characters were read;
otherwise it returns a pointer to the NUL terminated line.
.fX fpgetline()
never adds a newline to the buffer.
The user can check for a missing final newline in a file by checking
the EOF flag of the stream pointer when
.fX fpgetline()
returns a non-NULL pointer.
.LP
When
.fX fpgetline()
returns 
.fX NULL
the caller should check with
.fX ferror(3)
whether the cause was EOF or an error reading the stream
.fX fp .
.LP
.fX fpgetline()
returns a pointer to a static buffer that is resized as necessary
to handle long lines.
The caller can modify the contents of the buffer but must not free
it or realloc it.
The buffer is valid only until the next call of
.fX fpgetline() .
.Vs
char *config_trim_line(char *line)
.Ve
.fX config_trim_line()
trims comments and white space in place from a line.
First it scans for the first
.fX # ' `
character in the line.
If there is one it is removed along with any following characters.
Then leading and trailing whitespace characters (as defined by
.IR isspace (3))
are removed.
.fX config_trim_line()
returns a pointer to the trimmed line (which will point into the line
that it was given).
.LP
A typical use of this routine is to skip blank lines and comments from
a configuration file.
.Vs
typedef void (*errf_ofunc_t)(const char *string);
.sp
void errf(const char *fmt, ...)
char *strf(const char *fmt, ...)
.sp
errf_ofunc_t errf_set_ofunc(errf_ofunc_t func)
const char *errf_set_prefix(const char *prefix)
const char *errf_get_prefix(void)
void_errf_set_progname(const char *progname)
const char *errf_get_progname(void)
char *formf(char *buffer, int buffer_size,
            const char *format, va_list args)
void errf_usage(const char *usage)
.Ve
These routines form the basis of a generalised error handling system.
.fX errf()
formats an error message, much like
.fX printf(3) ,
but then passes the formatted text to the `current output function'.
The default output function appends a newline to the message and
sends it to stderr.
An alternative output function can be installed with
.fX errf_set_ofunc() ;
it returns the old one which can be re-installed as required.
The default output function can optionally prefix the message with
a fixed string; this can be inserted with
.fX errf_set_prefix() .
A pointer to the current prefix is returned by
.fX errf_get_prefix() .
By convention, this prefix is derived from the name of the program.
.fX errf_set_progname()
is a convenience routine which, when passed
.fX argv[0] ,
munges it in an operating system specific way to produce the program name
and sets the prefix to something that looks `nice'.
A pointer to the program name (after munging) can be obtained by
.fX errf_get_progname().
A usage line can be sent to the current output function by
.fX errf_usage() ;
it prefixes
.Vs
Usage: \fIprogname\fP
.Ve
to its argument, and exits with status 1.
.LP
.fX strf()
formats a string in the same way as
.fX errf() ,
but returns a pointer to a buffer obtained from
.fX malloc(3)
that
contains the result.
.LP
.fX formf()
is used in the internal implementation of
.fX errf()
and
.fX strf()
and
.fX logf()
(see below) and is not for the faint-hearted.
It is made visible because it is useful if you need to implement
other
.fX errf() "-style"
functions.
In addition to the normal format conversions,
.fX formf()
provides
.fX %m ' `
which inserts an error message
corresponding to the current value of
.fX errno
into the output string.
.Vs
int logf_set_ofile PROTO((const char *filename, const char *prefix));
void logf(int level, const char *fmt, ...)
int logf_set_level PROTO((int level));
void logf_errf_ofunc PROTO((const char *str));
.Ve
These routines are an alternative to
.I syslog (3)
for applications that need to log messages to a specified file.
.fX logf()
handles the
.fX fmt
format string and arguments in the same same way as
.fX errf() .
If there has been no prior call to
.fX logf_set_ofile ()
(see below) the message is 
displayed on stderr, prefixed with the current date and time.
If the output
.I is
going to a file,
.fX logf()
tries to ensure that messages from multiple processes to a single log
file are interleaved correctly.
.LP
The
.fX level
argument specifies the class of the message; it is one of
.fX LG_DEBUG ,
.fX LG_INFO ,
or
.fX LG_ERR
(which are in increasing numerical order).
Messages at a level less than the current log level are discarded.
The default log level is
.fX LG_INFO ;
it can be set using
.fX logf_set_level() ,
which also returns the previous log level.
The log levels
.fX LG_ALL
and
.fX LG_LOG
are valid only in calls to
.fX logf_set_level() ;
.fX LG_ALL
means log all messages and
.fX LG_LOG
means log only messages relating to
.fX logf()
itself.
.LP
.fX logf_set_ofile()
sets the output file for
.fX logf()
messages.
If the log file does not exist
.fX logf_set_ofile()
attempts to create it; otherwise it is opened for writing (without
discarding any existing contents).
If the attempt to create or open the file fails,
.fX logf_set_ofile()
gives an error message and returns -1, otherwise it returns zero.
If the
.fX prefix
argument is not
.fX NULL ,
the string specified is prepended to all future log messages.
.fX logf_set_ofile()
makes a copy of the string so it need not be preserved after the call.
.LP
.fX logf_errf_ofunc()
logs the message
.fX str
at level
.fX LG_ERR .
It can be passed as an output function to
.fX errf_set_ofunc()
to arrange that all error messages are sent to a log file.
.Ve
.fX ssplit()
splits a string into a vector of words, treating
occurrences in the string of any of the characters in the
.fX delimiters
string as word separators.
.LP
If the delimiters string starts with a NUL character then multiple
adjacent delimiters and leading delimiters generate zero length fields.
Otherwise, leading delimiter characters are skipped and multiple adjacent
delimiters are treated as a single delimiter.
Thus
.Vs
char **words = ssplit(line, " \\t");
.Ve
will to a shell-like split of a command line into words, and
.Vs
char **fields = ssplit(pwline, "\\0:");
.Ve
would be good for splitting lines from the password file.
.LP
.fX ssplit()
returns a
.fX NULL
terminated vector of words.
The space for this vector and the pointed to words is allocated with
a (single) call to
.fX e_malloc() .
.fX ssplit()
thus never returns
.fX NULL ;
it aborts the program
by calling
.fX panic()
if memory runs out.
.LP
The vector returned by
.fX ssplit()
should be freed when it is finished
with by passing it to
.fX free() .
.Vs
int get_host_addr(const char *hostname, struct in_addr *p_addr)
.Ve
.fX get_host_addr()
looks up the IP address of
.fX hostname
using
.IR gethostbyaddr (3).
If the lookup succeeds it sets
.fX *p_addr
to the IP address of the host in network byte order.
If the lookup fails it gives an error message with
.fX errf()
and returns -1.
If
.fX hostname
consists of four decimal numbers separated by dots then
.fX get_host_addr
parses this as an IP quad and does not call
.IR gethostbyname .
.Vs
int get_service_port(const char *servname, int *p_port)
.Ve
.fX get_service_port
looks up the port number of the TCP service
.fX servname
using
.IR getservbyname (3).
If it succeeds it sets
.fX *p_port
to the port number in network byte order.
Otherwise it gives an error message with
.fX errf()
and returns -1.
If
.fX servname
is an \s-2ASCII\s0 decimal number then
.fX get_service_port()
returns that number (again in network byte order).
.Vs
ebuf_t *ebuf_create(bool errors_are_fatal);
void ebuf_reset(ebuf_t *eb);
ebuf_t *ebuf_start(ebuf_t *eb, bool errors_are_fatal);
int ebuf_add(ebuf_t *eb, const char *buf, int count);
char *ebuf_get(ebuf_t *eb, int *p_len);
void ebuf_free(ebuf_t *eb);
.Ve
These routines implement variable sized contiguous buffers to which data
can be appended at any time.
.fX ebuf_create()
creates a new zero length buffer.
The
.fX errors_are_fatal
parameter controls the handling of errors; if it is
.fX TRUE
then all of the routines will call
.fX panic()
on failure.
.LP

.fX ebuf_add()
appends
.fX count
bytes of memory pointed at by
.fX data
to the buffer
.fX eb
(which must have been created using
.fX ebuf_create() ).
.fX ebuf_add()
returns zero on success.
On failure it panics or returns
.fX -1
(depending on the setting of
.fX errors_are_fatal
in the call of
.fX ebuf_create()).
.LP
.fX ebuf_get()
returns a pointer to the current contents of
.fX eb ;
if the
.fX p_len
parameter is not
.fX NULL
the current length of the buffer in bytes is stored there.
The returned buffer and length are only valid up to the next call of 
.fX ebuf_add() ,
.fX ebuf_reset()
or
.fX ebuf_free().
.LP
.fX ebuf_reset()
frees the data associated with
.fX eb
and resets the length to zero.
Furthur calls of
.fX ebuf_add()
can be used to add fresh data to
.fX eb .
.fX ebuf_free()
frees and destroys
.fX eb .
.LP
.fX ebuf_start()
is a convenience routine which either creates or resets a buffer.
If
.fX eb
is
.fX NULL
it calls
.fX ebuf_create()
with the supplied value of
.fX errors_are_fatal .
If
.fX eb
is not
.fX NULL
then it is passed to
.fX ebuf_reset().
The routine is intended to be used like for static buffers in the following
way:
.Vs
void foo(void)
{
        static ebuf_t *eb = NULL;
        
        eb = ebuf_start(eb, TRUE);
        ...
}
.Ve
The first time the function is called the buffer is created; on subsequent
calls it is reset.
.Vs
alloc_pool_t *alloc_create_pool(void)
.sp
void *alloc(alloc_pool_t *ap, int nbytes)
void *alloc_ck(alloc_pool_t *ap, int nbytes)
.Ve
.fX alloc_create_pool()
creates a memory allocation `pool' and
returns a handle referring to it.
.fX alloc()
allocates memory like
.fX malloc(3)
but from the
specified pool rather from the general malloc arena.
.fX alloc()
calls
.fX e_malloc()
to obtain memory in reasonably
large chunks when necessary.
This means that it never returns
.fX NULL ;
the program is aborted
via
.fX panic()
if there is insufficient memory to satisfy the
request.
The alternative interface
.fX alloc_ck()
returns
.fX NULL
if
it runs out of memory; it is otherwise identical to
.fX alloc() .
Memory obtained with
.fX alloc()
cannot be freed individually; only
entire pools can be freed.
.Vs
void alloc_free_pool(alloc_pool_t *ap)
void alloc_reset_pool(alloc_pool_t *ap)
.Ve
.fX alloc_free_pool()
frees an alloc pool, releasing all memory
allocated from it with
.fX alloc() .
The pool is no longer valid after this call.
.fX alloc_reset_pool()
conceptually frees all the memory associated with
a pool but does not return it via
.fX free() .
The pool remains valid and subsequent calls to
.fX alloc()
allocate
memory from the existing memory associated with the pool if possible.
.LP
These routines are suitable for applications which make lots of small
allocations for a data structure which is to be freed in one go.
.fX alloc()
is much faster than
.fX malloc()
as it does not do
the bookkeeping to support individual freeing of allocated memory.
It also has no space overhead other than that necessary to correctly
align objects in memory.
.LP
.fX alloc_create_pool()
is a lightweight routine \- it involves a
single call to
.fX malloc()
plus some assignments to initialise the
pool header structure.
It is thus reasonable to use the
.fX alloc()
routines in situations where
there are only going to be a few tens of calls to
.fX alloc() .
.Vs
bool alloc_set_default_debug_flag(bool val)
bool alloc_set_debug_flag(alloc_pool_t *ap, bool val)
.Ve
By default all memory obtained with
.fX alloc()
and related routines
is initialised to the repeated byte
.fX 0x53 .
When memory is freed (with
.fX alloc_free_pool() ,
.fX alloc_reset_pool()
or
.fX alloc_release() )
it is set
to the repeated byte
.fX 0x42 .
This is intended to trap erroneous use of uninitialised data and data
that has been freed \- newly allocated memory contains obvious garbage
and freed memory is immediately stamped on.
.LP
Of course these safety features cost speed, so they can be turned off
globally or per-pool.
.fX alloc_set_debug_flag()
sets the debugging flag for a pool; memory
will be initialised to garbage and stamped on when freed only of the flag
is non-zero.
.fX alloc_set_default_debug_flag()
sets the value of the flag used
for pools created from then on with
.fX alloc_create_pool() .
Both routines return the previous value of the flag they set.
.Vs
char *allocstr(alloc_pool_t *ap, int nbytes)
char *allocstr_ck(alloc_pool_t *ap, int nbytes)
.Ve
.fX allocstr()
is like
.fX alloc()
except that it assumes that
no alignment is required.
It is thus suitable only for allocating space for strings.
.fX allocstr()
is implemented such that interspersed calls to
.fX alloc()
and
.fX allocstr()
will pack both
the strings and the other objects tightly in memory with no space
wasted on alignment.
.fX allocstr()
never returns
.fX NULL
\- it panics like
.fX alloc()
if there is no memory.
.fX allocstr_ck()
is the same as
.fX allocstr()
except that
it returns
.fX NULL
if there is no memory.
.Vs
char *alloc_strdup(alloc_pool_t *ap, const char *s)
.Ve
.fX alloc_strdup()
is a convenience routine that returns a pointer
to a copy of a string allocated using
.fX allocstr() .
Note that it will never return
.fX NULL
as it uses
.fX allocstr()
rather than
.fX allocstr_ck() .
.Vs
alloc_mark_t *alloc_mark(alloc_pool_t *ap)
void alloc_release(alloc_pool_t *ap, alloc_mark_t *am)
.Ve
.fX alloc_mark()
returns an opaque handle that `remembers' the
current position in an alloc pool.
A subsequent call to
.fX alloc_release()
conceptually frees all
memory allocated from the pool since the corresponding call of
.fX alloc_mark() .
Subsequent calls to
.fX alloc()
et al will reuse the freed memory.
A call to
.fX alloc_release()
renders invalid any marks that were
returned after the
.fX alloc_mark()
call that returned the mark
being passed to
.fX alloc_release() .
.Vs
const char *ukcprog_version(void)
.Ve
.fX ukcprog_version()
returns a string giving the current version number of the library.
.SH BUGS
This library treads rather freely on the name space.
.SH AUTHORS
.LP
Godfrey Paul
.br
Mark Russell
.sp
Computing Laboratory, University of Kent at Canterbury.
.br
Contact: cs-sysadmin@kent.ac.uk
Revision:	1.3
Committed:	Sun Aug 1 10:41:13 2004 UTC (20 years, 4 months ago) by tdb
Branch:	MAIN
CVS Tags:	HEAD
Changes since 1.2:	+1 -1 lines
Log Message:	Catch a lot of old URL's and update them. Also remove a couple of old files that aren't used.
#	User	Rev	Content
1	tdb	1.1	.\" $Id: ukcprog.3,v 1.18 1993/02/23 11:31:42 gjap Exp $ UKC
2			.\" .fX - print the argument in a fixed font
3			.de fX
4			\&\\$3\f(CR\\$1\fP\\$2
5			..
6			.\" .Vs - start example
7			.de Vs
8			.LP
9			.ne 1i
10			.RS
11			.nf
12			.ft CR
13			..
14			.\" .Ve - end example
15			.de Ve
16			.ft P
17			.fi
18			.hy 0
19			.RE
20			.LP
21			..
22			.TH UKCPROG 3 "February 1991" "UKC Local"
23			.SH NAME
24			ukcprog \- Library of utilities for C programmers
25			.SH SYNOPSIS
26			.nf
27			.LP
28			In source code,
29			.Vs
30	tdb	1.2	#include <ukcprog.h>
31	tdb	1.1	.Ve
32			and link with
33			.Vs
34			cc ... -lukcprog
35			.Ve
36			.SH AVAILABILITY
37			.LP
38			.\"
39			.\" The following sentence motivated the port to MS-DOG.
40			.\"
41			This is a UKC library, available for the \s-1UNIX\s0 and \s-1VMS\s0
42			operating systems, and for MS-DOS.
43			.\"
44			.\" It was worth it ...
45			.\"
46			The source code is freely available so if you want to make
47			a source release of your application you can include a copy of the
48			source of this library as well.
49			.SH DESCRIPTION
50			.LP
51			The ukcprog library contains generally useful low level routines.
52			The
53			.fX ukcprog.h
54			header file contains prototypes for the
55			routines as well as defining some useful macros and types.
56			.Vs
57			#ifdef __STDC__
58			#define PROTO(a) a
59			typedef void *voidptr;
60			#else
61			#define PROTO(a) ()
62			#define const
63			#define volatile
64			#define signed
65			typedef char *voidptr;
66			#endif
67			.Ve
68			.LP
69			The definitions of
70			.fX const ,
71			.fX volatile
72			and
73			.fX signed
74			allow these ANSI C keywords to be used in code which must be portable
75			to pre-ANSI C compilers.
76			.LP
77			The
78			.fX voidptr
79			typedef is similarly there to help with code for pre-ANSI compilers
80			which do not support the
81			.fX "void *" ' `
82			type.
83			Functions which are documented here as returning
84			.fX "void *" ' `
85			return
86			.fX "char *" ' `
87			when compiling with a non-ANSI C compiler.
88			.LP
89			The
90			.fX PROTO
91			macro is useful for declaring function prototypes
92			for use with ANSI C while still allowing the code to be compiled with
93			K&R compilers.
94			It is used thus:
95			.Vs
96			int myfunc PROTO((int arg1, char *arg2));
97			.Ve
98			With an ANSI C compiler this expands to
99			.Vs
100			int myfunc (int arg1, char *arg2);
101			.Ve
102			whereas a pre-ANSI compiler sees:
103			.Vs
104			int myfunc ();
105			.Ve
106			.LP
107			Note the double brackets; these are necessary to make all the parameters
108			a single argument to the
109			.fX PROTO
110			macro.
111			.Vs
112			#ifndef FALSE
113			#define FALSE 0
114			#endif
115			#ifndef TRUE
116			#define TRUE 1
117			#endif
118			#ifndef bool
119			#define bool int
120			#endif
121			.Ve
122			These define the commonly used
123			.fX TRUE
124			and
125			.fX FALSE
126			macros to their usual values.
127			The definitions are protected in case these are already defined.
128			The
129			.fX bool
130			macro is intended to be used to declared variables
131			that are conceptually boolean.
132			A
133			.fX #define
134			is used rather than a typedef because there might already be a typedef
135			for
136			.fX bool .
137			.Vs
138			#ifdef __STDC__
139			#define CAT(a,b) a ## b
140			#else
141			#define _IDENT(a) a
142			#define CAT(a,b) _IDENT(a)b
143			#endif /* !__STDC__ */
144			.Ve
145			The
146			.fX CAT
147			macro can be used to glue two tokens together in the same way as
148			the ANSI C
149			.fX ##
150			operator.
151			.fX CAT
152			also works with many (but not all) pre-ANSI C preprocessors.
153			.Vs
154			void panic(const char *message)
155			.sp
156			typedef void (panic_handler_t)(const char message);
157			panic_handler_t install_panic_handler(panic_hander_t handler)
158			.Ve
159			By default
160			.fX panic()
161			produces a message on stderr of the form
162			.Vs
163			fatal internal error: \fIsomething\fP (aborting)...
164			.Ve
165			It then calls
166			.fX abort(3)
167			to produce a core dump.
168			Alternative `panic handlers' can be installed using
169			.fX install_panic_handler()
170			which returns the previous handler.
171			Panic handlers can perform tidy-up tasks, such as
172			removing temporary files or calling
173			.fX chdir(2)
174			to arrange for
175			the core to land in a safe place.
176			If a panic handler is called and returns then the default
177			action is carried out.
178			.Vs
179			void *e_malloc(size_t size)
180			void e_realloc(void old, size_t size)
181			char strsave(const char str)
182			.Ve
183			.fX e_malloc()
184			and
185			.fX e_realloc()
186			are error-checking versions
187			of the corresponding routines in the standard C library.
188			They call
189			.fX panic()
190			if the request fails.
191			.fX e_realloc()
192			behaves according to the ANSI specification for
193			.fX realloc() ;
194			that is, if
195			.fX old
196			is NULL it behaves like
197			.fX malloc()
198			and if size is 0, it behaves like
199			.fX free() .
200			.fX strsave()
201			allocates some memory using
202			.fX e_malloc() ,
203			copies
204			.fX str
205			into it, and returns a pointer to the copy.
206			.Vs
207			char fpgetline(FILE fp)
208			.Ve
209			.fX fpgetline()
210			reads characters from the standard IO stream
211			.fX fp
212			until a newline character or EOF is encountered.
213			.fX fpgetline()
214			returns
215			.fX NULL
216			if EOF or an error occurred before any characters were read;
217			otherwise it returns a pointer to the NUL terminated line.
218			.fX fpgetline()
219			never adds a newline to the buffer.
220			The user can check for a missing final newline in a file by checking
221			the EOF flag of the stream pointer when
222			.fX fpgetline()
223			returns a non-NULL pointer.
224			.LP
225			When
226			.fX fpgetline()
227			returns
228			.fX NULL
229			the caller should check with
230			.fX ferror(3)
231			whether the cause was EOF or an error reading the stream
232			.fX fp .
233			.LP
234			.fX fpgetline()
235			returns a pointer to a static buffer that is resized as necessary
236			to handle long lines.
237			The caller can modify the contents of the buffer but must not free
238			it or realloc it.
239			The buffer is valid only until the next call of
240			.fX fpgetline() .
241			.Vs
242			char config_trim_line(char line)
243			.Ve
244			.fX config_trim_line()
245			trims comments and white space in place from a line.
246			First it scans for the first
247			.fX # ' `
248			character in the line.
249			If there is one it is removed along with any following characters.
250			Then leading and trailing whitespace characters (as defined by
251			.IR isspace (3))
252			are removed.
253			.fX config_trim_line()
254			returns a pointer to the trimmed line (which will point into the line
255			that it was given).
256			.LP
257			A typical use of this routine is to skip blank lines and comments from
258			a configuration file.
259			.Vs
260			typedef void (errf_ofunc_t)(const char string);
261			.sp
262			void errf(const char *fmt, ...)
263			char strf(const char fmt, ...)
264			.sp
265			errf_ofunc_t errf_set_ofunc(errf_ofunc_t func)
266			const char errf_set_prefix(const char prefix)
267			const char *errf_get_prefix(void)
268			void_errf_set_progname(const char *progname)
269			const char *errf_get_progname(void)
270			char formf(char buffer, int buffer_size,
271			const char *format, va_list args)
272			void errf_usage(const char *usage)
273			.Ve
274			These routines form the basis of a generalised error handling system.
275			.fX errf()
276			formats an error message, much like
277			.fX printf(3) ,
278			but then passes the formatted text to the `current output function'.
279			The default output function appends a newline to the message and
280			sends it to stderr.
281			An alternative output function can be installed with
282			.fX errf_set_ofunc() ;
283			it returns the old one which can be re-installed as required.
284			The default output function can optionally prefix the message with
285			a fixed string; this can be inserted with
286			.fX errf_set_prefix() .
287			A pointer to the current prefix is returned by
288			.fX errf_get_prefix() .
289			By convention, this prefix is derived from the name of the program.
290			.fX errf_set_progname()
291			is a convenience routine which, when passed
292			.fX argv[0] ,
293			munges it in an operating system specific way to produce the program name
294			and sets the prefix to something that looks `nice'.
295			A pointer to the program name (after munging) can be obtained by
296			.fX errf_get_progname().
297			A usage line can be sent to the current output function by
298			.fX errf_usage() ;
299			it prefixes
300			.Vs
301			Usage: \fIprogname\fP
302			.Ve
303			to its argument, and exits with status 1.
304			.LP
305			.fX strf()
306			formats a string in the same way as
307			.fX errf() ,
308			but returns a pointer to a buffer obtained from
309			.fX malloc(3)
310			that
311			contains the result.
312			.LP
313			.fX formf()
314			is used in the internal implementation of
315			.fX errf()
316			and
317			.fX strf()
318			and
319			.fX logf()
320			(see below) and is not for the faint-hearted.
321			It is made visible because it is useful if you need to implement
322			other
323			.fX errf() "-style"
324			functions.
325			In addition to the normal format conversions,
326			.fX formf()
327			provides
328			.fX %m ' `
329			which inserts an error message
330			corresponding to the current value of
331			.fX errno
332			into the output string.
333			.Vs
334			int logf_set_ofile PROTO((const char filename, const char prefix));
335			void logf(int level, const char *fmt, ...)
336			int logf_set_level PROTO((int level));
337			void logf_errf_ofunc PROTO((const char *str));
338			.Ve
339			These routines are an alternative to
340			.I syslog (3)
341			for applications that need to log messages to a specified file.
342			.fX logf()
343			handles the
344			.fX fmt
345			format string and arguments in the same same way as
346			.fX errf() .
347			If there has been no prior call to
348			.fX logf_set_ofile ()
349			(see below) the message is
350			displayed on stderr, prefixed with the current date and time.
351			If the output
352			.I is
353			going to a file,
354			.fX logf()
355			tries to ensure that messages from multiple processes to a single log
356			file are interleaved correctly.
357			.LP
358			The
359			.fX level
360			argument specifies the class of the message; it is one of
361			.fX LG_DEBUG ,
362			.fX LG_INFO ,
363			or
364			.fX LG_ERR
365			(which are in increasing numerical order).
366			Messages at a level less than the current log level are discarded.
367			The default log level is
368			.fX LG_INFO ;
369			it can be set using
370			.fX logf_set_level() ,
371			which also returns the previous log level.
372			The log levels
373			.fX LG_ALL
374			and
375			.fX LG_LOG
376			are valid only in calls to
377			.fX logf_set_level() ;
378			.fX LG_ALL
379			means log all messages and
380			.fX LG_LOG
381			means log only messages relating to
382			.fX logf()
383			itself.
384			.LP
385			.fX logf_set_ofile()
386			sets the output file for
387			.fX logf()
388			messages.
389			If the log file does not exist
390			.fX logf_set_ofile()
391			attempts to create it; otherwise it is opened for writing (without
392			discarding any existing contents).
393			If the attempt to create or open the file fails,
394			.fX logf_set_ofile()
395			gives an error message and returns -1, otherwise it returns zero.
396			If the
397			.fX prefix
398			argument is not
399			.fX NULL ,
400			the string specified is prepended to all future log messages.
401			.fX logf_set_ofile()
402			makes a copy of the string so it need not be preserved after the call.
403			.LP
404			.fX logf_errf_ofunc()
405			logs the message
406			.fX str
407			at level
408			.fX LG_ERR .
409			It can be passed as an output function to
410			.fX errf_set_ofunc()
411			to arrange that all error messages are sent to a log file.
412			.Ve
413			.fX ssplit()
414			splits a string into a vector of words, treating
415			occurrences in the string of any of the characters in the
416			.fX delimiters
417			string as word separators.
418			.LP
419			If the delimiters string starts with a NUL character then multiple
420			adjacent delimiters and leading delimiters generate zero length fields.
421			Otherwise, leading delimiter characters are skipped and multiple adjacent
422			delimiters are treated as a single delimiter.
423			Thus
424			.Vs
425			char **words = ssplit(line, " \\t");
426			.Ve
427			will to a shell-like split of a command line into words, and
428			.Vs
429			char **fields = ssplit(pwline, "\\0:");
430			.Ve
431			would be good for splitting lines from the password file.
432			.LP
433			.fX ssplit()
434			returns a
435			.fX NULL
436			terminated vector of words.
437			The space for this vector and the pointed to words is allocated with
438			a (single) call to
439			.fX e_malloc() .
440			.fX ssplit()
441			thus never returns
442			.fX NULL ;
443			it aborts the program
444			by calling
445			.fX panic()
446			if memory runs out.
447			.LP
448			The vector returned by
449			.fX ssplit()
450			should be freed when it is finished
451			with by passing it to
452			.fX free() .
453			.Vs
454			int get_host_addr(const char hostname, struct in_addr p_addr)
455			.Ve
456			.fX get_host_addr()
457			looks up the IP address of
458			.fX hostname
459			using
460			.IR gethostbyaddr (3).
461			If the lookup succeeds it sets
462			.fX *p_addr
463			to the IP address of the host in network byte order.
464			If the lookup fails it gives an error message with
465			.fX errf()
466			and returns -1.
467			If
468			.fX hostname
469			consists of four decimal numbers separated by dots then
470			.fX get_host_addr
471			parses this as an IP quad and does not call
472			.IR gethostbyname .
473			.Vs
474			int get_service_port(const char servname, int p_port)
475			.Ve
476			.fX get_service_port
477			looks up the port number of the TCP service
478			.fX servname
479			using
480			.IR getservbyname (3).
481			If it succeeds it sets
482			.fX *p_port
483			to the port number in network byte order.
484			Otherwise it gives an error message with
485			.fX errf()
486			and returns -1.
487			If
488			.fX servname
489			is an \s-2ASCII\s0 decimal number then
490			.fX get_service_port()
491			returns that number (again in network byte order).
492			.Vs
493			ebuf_t *ebuf_create(bool errors_are_fatal);
494			void ebuf_reset(ebuf_t *eb);
495			ebuf_t ebuf_start(ebuf_t eb, bool errors_are_fatal);
496			int ebuf_add(ebuf_t eb, const char buf, int count);
497			char ebuf_get(ebuf_t eb, int *p_len);
498			void ebuf_free(ebuf_t *eb);
499			.Ve
500			These routines implement variable sized contiguous buffers to which data
501			can be appended at any time.
502			.fX ebuf_create()
503			creates a new zero length buffer.
504			The
505			.fX errors_are_fatal
506			parameter controls the handling of errors; if it is
507			.fX TRUE
508			then all of the routines will call
509			.fX panic()
510			on failure.
511			.LP
512
513			.fX ebuf_add()
514			appends
515			.fX count
516			bytes of memory pointed at by
517			.fX data
518			to the buffer
519			.fX eb
520			(which must have been created using
521			.fX ebuf_create() ).
522			.fX ebuf_add()
523			returns zero on success.
524			On failure it panics or returns
525			.fX -1
526			(depending on the setting of
527			.fX errors_are_fatal
528			in the call of
529			.fX ebuf_create()).
530			.LP
531			.fX ebuf_get()
532			returns a pointer to the current contents of
533			.fX eb ;
534			if the
535			.fX p_len
536			parameter is not
537			.fX NULL
538			the current length of the buffer in bytes is stored there.
539			The returned buffer and length are only valid up to the next call of
540			.fX ebuf_add() ,
541			.fX ebuf_reset()
542			or
543			.fX ebuf_free().
544			.LP
545			.fX ebuf_reset()
546			frees the data associated with
547			.fX eb
548			and resets the length to zero.
549			Furthur calls of
550			.fX ebuf_add()
551			can be used to add fresh data to
552			.fX eb .
553			.fX ebuf_free()
554			frees and destroys
555			.fX eb .
556			.LP
557			.fX ebuf_start()
558			is a convenience routine which either creates or resets a buffer.
559			If
560			.fX eb
561			is
562			.fX NULL
563			it calls
564			.fX ebuf_create()
565			with the supplied value of
566			.fX errors_are_fatal .
567			If
568			.fX eb
569			is not
570			.fX NULL
571			then it is passed to
572			.fX ebuf_reset().
573			The routine is intended to be used like for static buffers in the following
574			way:
575			.Vs
576			void foo(void)
577			{
578			static ebuf_t *eb = NULL;
579
580			eb = ebuf_start(eb, TRUE);
581			...
582			}
583			.Ve
584			The first time the function is called the buffer is created; on subsequent
585			calls it is reset.
586			.Vs
587			alloc_pool_t *alloc_create_pool(void)
588			.sp
589			void alloc(alloc_pool_t ap, int nbytes)
590			void alloc_ck(alloc_pool_t ap, int nbytes)
591			.Ve
592			.fX alloc_create_pool()
593			creates a memory allocation `pool' and
594			returns a handle referring to it.
595			.fX alloc()
596			allocates memory like
597			.fX malloc(3)
598			but from the
599			specified pool rather from the general malloc arena.
600			.fX alloc()
601			calls
602			.fX e_malloc()
603			to obtain memory in reasonably
604			large chunks when necessary.
605			This means that it never returns
606			.fX NULL ;
607			the program is aborted
608			via
609			.fX panic()
610			if there is insufficient memory to satisfy the
611			request.
612			The alternative interface
613			.fX alloc_ck()
614			returns
615			.fX NULL
616			if
617			it runs out of memory; it is otherwise identical to
618			.fX alloc() .
619			Memory obtained with
620			.fX alloc()
621			cannot be freed individually; only
622			entire pools can be freed.
623			.Vs
624			void alloc_free_pool(alloc_pool_t *ap)
625			void alloc_reset_pool(alloc_pool_t *ap)
626			.Ve
627			.fX alloc_free_pool()
628			frees an alloc pool, releasing all memory
629			allocated from it with
630			.fX alloc() .
631			The pool is no longer valid after this call.
632			.fX alloc_reset_pool()
633			conceptually frees all the memory associated with
634			a pool but does not return it via
635			.fX free() .
636			The pool remains valid and subsequent calls to
637			.fX alloc()
638			allocate
639			memory from the existing memory associated with the pool if possible.
640			.LP
641			These routines are suitable for applications which make lots of small
642			allocations for a data structure which is to be freed in one go.
643			.fX alloc()
644			is much faster than
645			.fX malloc()
646			as it does not do
647			the bookkeeping to support individual freeing of allocated memory.
648			It also has no space overhead other than that necessary to correctly
649			align objects in memory.
650			.LP
651			.fX alloc_create_pool()
652			is a lightweight routine \- it involves a
653			single call to
654			.fX malloc()
655			plus some assignments to initialise the
656			pool header structure.
657			It is thus reasonable to use the
658			.fX alloc()
659			routines in situations where
660			there are only going to be a few tens of calls to
661			.fX alloc() .
662			.Vs
663			bool alloc_set_default_debug_flag(bool val)
664			bool alloc_set_debug_flag(alloc_pool_t *ap, bool val)
665			.Ve
666			By default all memory obtained with
667			.fX alloc()
668			and related routines
669			is initialised to the repeated byte
670			.fX 0x53 .
671			When memory is freed (with
672			.fX alloc_free_pool() ,
673			.fX alloc_reset_pool()
674			or
675			.fX alloc_release() )
676			it is set
677			to the repeated byte
678			.fX 0x42 .
679			This is intended to trap erroneous use of uninitialised data and data
680			that has been freed \- newly allocated memory contains obvious garbage
681			and freed memory is immediately stamped on.
682			.LP
683			Of course these safety features cost speed, so they can be turned off
684			globally or per-pool.
685			.fX alloc_set_debug_flag()
686			sets the debugging flag for a pool; memory
687			will be initialised to garbage and stamped on when freed only of the flag
688			is non-zero.
689			.fX alloc_set_default_debug_flag()
690			sets the value of the flag used
691			for pools created from then on with
692			.fX alloc_create_pool() .
693			Both routines return the previous value of the flag they set.
694			.Vs
695			char allocstr(alloc_pool_t ap, int nbytes)
696			char allocstr_ck(alloc_pool_t ap, int nbytes)
697			.Ve
698			.fX allocstr()
699			is like
700			.fX alloc()
701			except that it assumes that
702			no alignment is required.
703			It is thus suitable only for allocating space for strings.
704			.fX allocstr()
705			is implemented such that interspersed calls to
706			.fX alloc()
707			and
708			.fX allocstr()
709			will pack both
710			the strings and the other objects tightly in memory with no space
711			wasted on alignment.
712			.fX allocstr()
713			never returns
714			.fX NULL
715			\- it panics like
716			.fX alloc()
717			if there is no memory.
718			.fX allocstr_ck()
719			is the same as
720			.fX allocstr()
721			except that
722			it returns
723			.fX NULL
724			if there is no memory.
725			.Vs
726			char alloc_strdup(alloc_pool_t ap, const char *s)
727			.Ve
728			.fX alloc_strdup()
729			is a convenience routine that returns a pointer
730			to a copy of a string allocated using
731			.fX allocstr() .
732			Note that it will never return
733			.fX NULL
734			as it uses
735			.fX allocstr()
736			rather than
737			.fX allocstr_ck() .
738			.Vs
739			alloc_mark_t alloc_mark(alloc_pool_t ap)
740			void alloc_release(alloc_pool_t ap, alloc_mark_t am)
741			.Ve
742			.fX alloc_mark()
743			returns an opaque handle that `remembers' the
744			current position in an alloc pool.
745			A subsequent call to
746			.fX alloc_release()
747			conceptually frees all
748			memory allocated from the pool since the corresponding call of
749			.fX alloc_mark() .
750			Subsequent calls to
751			.fX alloc()
752			et al will reuse the freed memory.
753			A call to
754			.fX alloc_release()
755			renders invalid any marks that were
756			returned after the
757			.fX alloc_mark()
758			call that returned the mark
759			being passed to
760			.fX alloc_release() .
761			.Vs
762			const char *ukcprog_version(void)
763			.Ve
764			.fX ukcprog_version()
765			returns a string giving the current version number of the library.
766			.SH BUGS
767			This library treads rather freely on the name space.
768			.SH AUTHORS
769			.LP
770	tdb	1.2	Godfrey Paul
771	tdb	1.1	.br
772	tdb	1.2	Mark Russell
773	tdb	1.1	.sp
774			Computing Laboratory, University of Kent at Canterbury.
775	tdb	1.2	.br
776	tdb	1.3	Contact: cs-sysadmin@kent.ac.uk