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.
#	Content
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	#include <ukcprog.h>
31	.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	Godfrey Paul
771	.br
772	Mark Russell
773	.sp
774	Computing Laboratory, University of Kent at Canterbury.
775	.br
776	Contact: cs-sysadmin@kent.ac.uk