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