Manual Reference Pages - UKCPROG (3)
ukcprog - Library of utilities for C programmers
In source code,
and link with
cc ... -lukcprog
This is a UKC library, available for the UNIX and VMS
operating systems, and for MS-DOS.
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.
The ukcprog library contains generally useful low level routines.
header file contains prototypes for the
routines as well as defining some useful macros and types.
#define PROTO(a) a
typedef void *voidptr;
#define PROTO(a) ()
typedef char *voidptr;
The definitions of
allow these ANSI C keywords to be used in code which must be portable
to pre-ANSI C compilers.
typedef is similarly there to help with code for pre-ANSI compilers
which do not support the
Functions which are documented here as returning
when compiling with a non-ANSI C compiler.
macro is useful for declaring function prototypes
for use with ANSI C while still allowing the code to be compiled with
It is used thus:
int myfunc PROTO((int arg1, char *arg2));
With an ANSI C compiler this expands to
int myfunc (int arg1, char *arg2);
whereas a pre-ANSI compiler sees:
int myfunc ();
Note the double brackets; these are necessary to make all the parameters
a single argument to the
#define FALSE 0
#define TRUE 1
#define bool int
These define the commonly used
macros to their usual values.
The definitions are protected in case these are already defined.
macro is intended to be used to declared variables
that are conceptually boolean.
is used rather than a typedef because there might already be a typedef
#define CAT(a,b) a ## b
#define _IDENT(a) a
#define CAT(a,b) _IDENT(a)b
#endif /* !__STDC__ */
macro can be used to glue two tokens together in the same way as
the ANSI C
also works with many (but not all) pre-ANSI C preprocessors.
void panic(const char *message)
typedef void (*panic_handler_t)(const char *message);
panic_handler_t install_panic_handler(panic_hander_t handler)
produces a message on stderr of the form
fatal internal error: something (aborting)...
It then calls
to produce a core dump.
Alternative panic handlers can be installed using
which returns the previous handler.
Panic handlers can perform tidy-up tasks, such as
removing temporary files or calling
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.
void *e_malloc(size_t size)
void *e_realloc(void *old, size_t size)
char *strsave(const char *str)
are error-checking versions
of the corresponding routines in the standard C library.
if the request fails.
behaves according to the ANSI specification for
that is, if
is NULL it behaves like
and if size is 0, it behaves like
allocates some memory using
into it, and returns a pointer to the copy.
char *fpgetline(FILE *fp)
reads characters from the standard IO stream
until a newline character or EOF is encountered.
if EOF or an error occurred before any characters were read;
otherwise it returns a pointer to the NUL terminated line.
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
returns a non-NULL pointer.
the caller should check with
whether the cause was EOF or an error reading the stream
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
char *config_trim_line(char *line)
trims comments and white space in place from a line.
First it scans for the first
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
returns a pointer to the trimmed line (which will point into the line
that it was given).
A typical use of this routine is to skip blank lines and comments from
a configuration file.
typedef void (*errf_ofunc_t)(const char *string);
void errf(const char *fmt, ...)
char *strf(const char *fmt, ...)
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)
These routines form the basis of a generalised error handling system.
formats an error message, much like
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
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
A pointer to the current prefix is returned by
By convention, this prefix is derived from the name of the program.
is a convenience routine which, when passed
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
A usage line can be sent to the current output function by
to its argument, and exits with status 1.
formats a string in the same way as
but returns a pointer to a buffer obtained from
contains the result.
is used in the internal implementation of
(see below) and is not for the faint-hearted.
It is made visible because it is useful if you need to implement
In addition to the normal format conversions,
which inserts an error message
corresponding to the current value of
into the output string.
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));
These routines are an alternative to
syslog (3) for applications that need to log messages to a specified file.
format string and arguments in the same same way as
If there has been no prior call to
(see below) the message is
displayed on stderr, prefixed with the current date and time.
If the output
is going to a file,
tries to ensure that messages from multiple processes to a single log
file are interleaved correctly.
argument specifies the class of the message; it is one of
(which are in increasing numerical order).
Messages at a level less than the current log level are discarded.
The default log level is
it can be set using
which also returns the previous log level.
The log levels
are valid only in calls to
means log all messages and
means log only messages relating to
sets the output file for
If the log file does not exist
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,
gives an error message and returns -1, otherwise it returns zero.
argument is not
the string specified is prepended to all future log messages.
makes a copy of the string so it need not be preserved after the call.
logs the message
It can be passed as an output function to
to arrange that all error messages are sent to a log file.
splits a string into a vector of words, treating
occurrences in the string of any of the characters in the
string as word separators.
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.
char **words = ssplit(line, " \t");
will to a shell-like split of a command line into words, and
char **fields = ssplit(pwline, "\0:");
would be good for splitting lines from the password file.
terminated vector of words.
The space for this vector and the pointed to words is allocated with
a (single) call to
thus never returns
it aborts the program
if memory runs out.
The vector returned by
should be freed when it is finished
with by passing it to
int get_host_addr(const char *hostname, struct in_addr *p_addr)
looks up the IP address of
If the lookup succeeds it sets
to the IP address of the host in network byte order.
If the lookup fails it gives an error message with
and returns -1.
consists of four decimal numbers separated by dots then
parses this as an IP quad and does not call
int get_service_port(const char *servname, int *p_port)
looks up the port number of the TCP service
If it succeeds it sets
to the port number in network byte order.
Otherwise it gives an error message with
and returns -1.
is an ASCII decimal number then
returns that number (again in network byte order).
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);
These routines implement variable sized contiguous buffers to which data
can be appended at any time.
creates a new zero length buffer.
parameter controls the handling of errors; if it is
then all of the routines will call
bytes of memory pointed at by
to the buffer
(which must have been created using
returns zero on success.
On failure it panics or returns
(depending on the setting of
in the call of
returns a pointer to the current contents of
parameter is not
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
frees the data associated with
and resets the length to zero.
Furthur calls of
can be used to add fresh data to
frees and destroys
is a convenience routine which either creates or resets a buffer.
with the supplied value of
then it is passed to
The routine is intended to be used like for static buffers in the following
static ebuf_t *eb = NULL;
eb = ebuf_start(eb, TRUE);
The first time the function is called the buffer is created; on subsequent
calls it is reset.
void *alloc(alloc_pool_t *ap, int nbytes)
void *alloc_ck(alloc_pool_t *ap, int nbytes)
creates a memory allocation pool and
returns a handle referring to it.
allocates memory like
but from the
specified pool rather from the general malloc arena.
to obtain memory in reasonably
large chunks when necessary.
This means that it never returns
the program is aborted
if there is insufficient memory to satisfy the
The alternative interface
it runs out of memory; it is otherwise identical to
Memory obtained with
cannot be freed individually; only
entire pools can be freed.
void alloc_free_pool(alloc_pool_t *ap)
void alloc_reset_pool(alloc_pool_t *ap)
frees an alloc pool, releasing all memory
allocated from it with
The pool is no longer valid after this call.
conceptually frees all the memory associated with
a pool but does not return it via
The pool remains valid and subsequent calls to
memory from the existing memory associated with the pool if possible.
These routines are suitable for applications which make lots of small
allocations for a data structure which is to be freed in one go.
is much faster than
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.
is a lightweight routine - it involves a
single call to
plus some assignments to initialise the
pool header structure.
It is thus reasonable to use the
routines in situations where
there are only going to be a few tens of calls to
bool alloc_set_default_debug_flag(bool val)
bool alloc_set_debug_flag(alloc_pool_t *ap, bool val)
By default all memory obtained with
and related routines
is initialised to the repeated byte
When memory is freed (with
it is set
to the repeated byte
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.
Of course these safety features cost speed, so they can be turned off
globally or per-pool.
sets the debugging flag for a pool; memory
will be initialised to garbage and stamped on when freed only of the flag
sets the value of the flag used
for pools created from then on with
Both routines return the previous value of the flag they set.
char *allocstr(alloc_pool_t *ap, int nbytes)
char *allocstr_ck(alloc_pool_t *ap, int nbytes)
except that it assumes that
no alignment is required.
It is thus suitable only for allocating space for strings.
is implemented such that interspersed calls to
will pack both
the strings and the other objects tightly in memory with no space
wasted on alignment.
- it panics like
if there is no memory.
is the same as
if there is no memory.
char *alloc_strdup(alloc_pool_t *ap, const char *s)
is a convenience routine that returns a pointer
to a copy of a string allocated using
Note that it will never return
as it uses
alloc_mark_t *alloc_mark(alloc_pool_t *ap)
void alloc_release(alloc_pool_t *ap, alloc_mark_t *am)
returns an opaque handle that remembers the
current position in an alloc pool.
A subsequent call to
conceptually frees all
memory allocated from the pool since the corresponding call of
Subsequent calls to
et al will reuse the freed memory.
A call to
renders invalid any marks that were
returned after the
call that returned the mark
being passed to
const char *ukcprog_version(void)
returns a string giving the current version number of the library.
This library treads rather freely on the name space.
Computing Laboratory, University of Kent at Canterbury.
|UKC Local ||UKCPROG (3) ||February 1991 |
Visit the GSP FreeBSD Man Page Interface.
Output converted with manServer 1.07.