Index

libIvor - PROSE general purpose low-level library routines

CONTENTS

Synopsis
Description
Common Header Files
Interfaces
Type Definitions
Data Structures
Macro Interfaces
Macro Definitions
Custom Error Codes
Files
See Also
Author

cc -Iincludedir/prose [flag ...] file -lIvor [library ...]

#include <libIvor/Ivor_api.h>

General purpose library routines useful for providing low-level functionality in C programs. Specifically developed for the PROSE Programming Language this library may be used separately to PROSE in any C programming project that requires this functionality.

The library is detailed below in terms of COMMON HEADER FILES, INTERFACES, TYPE DEFINITIONS, DATA STRUCTURES, MACRO INTERFACES, MACRO DEFINITIONS and CUSTOM ERROR CODES. Symbols appear in alphabetical order. See the source code for lists of function arguments, return values and general usage guidelines.

This library is designed to work in a GNU Autoconf environment, where a configure script has created a config.h file containing macro definitions indicating the availability of features in the compilation environment. To use the library without GNU Autoconf, copy config.h from the library’s source directory after running configure on the target system, and make this header file available in your project’s include directory.

This library adds a number of portability features and checks that are designed to work in tandem with GNU Autoconf. These features require additional header files to be included, and are summarised below.

<common/boolean.h>
	Adds a bool type definition if one doesn’t already exist, and the TRUE and FALSE definitions.
<common/common.h>
	Includes standard system headers required for exit status and path limits, then defines PATH_MAX, EXIT_SUCCESS, EXIT_FAILURE and EXIT_PANIC if these do not already exist. Also includes <common/boolean.h>.
<common/decls.h>
	Creates the BEGIN_C_DECLS and END_C_DECLS definitions as required if __cplusplus is defined, and also defines PARAMS() and VOIDP to help developers write code that will work on both ANSI C and traditional K&R C compilers. PARAMS() is used for function prototypes, to discard its arguments if __STDC__ is not defined.
<common/inchead.h>
	Includes <common/decls.h>, <config.h> and any other system headers that have been requested through the use of INCL_<header> macros. Has some portability knowledge so it knows what other header files may be needed on certain platforms to achieve the desired results. Will also include <libIvor/replace.h> if functions are needed that do not exist in this build environment, e.g. replacement versions of mmap(), pathfind() and realloc(). Hides portability macros away from ordinary source code.
<common/package.h>
	Standard macros for defining the name of a tool, the package it is from and version information if this data hasn’t been supplied by the build environment.

Dlist_add()
	Add new data to a double linked list.
Dlist_del()
	Delete data from a double linked list.
Dlist_find()
	Find data in a double linked list.
Dlist_free()
	Free memory previously claimed by double linked list structure.
Dlist_init()
	Initialises a double linked list structure. In order to display error messages correctly, run Error_init() before calling this routine, and use the functions Error() or Error1() to report error messages. This function is actually implemented as a macro so that the 4th argument can be discarded if the library was not compiled following a configure --enable-extradebug.
Dlist_runfunc()
	Traverse a double linked list running a user supplied function on each data item.
Error()	Writes basic error message to given file stream.
Error1()
	Writes error message including given string (usually filename) to stream.
Error_add()
	Adds new error codes and messages to the global array previously initialised with Error_init(). These take the form of an array of errcode structures, that will then be reported by Error() and Error1().
Error_init()
	Initialise custom error codes that are used by this library, and prepare to accept new error code definitions from Error_add().
Error_str()
	Returns a pointer to a null terminated character array containing a description of the error described by the supplied error number. This is a wrapper for the standard strerror() routine, and is needed to handle custom error codes.
Find_my_config()
	Locates a named configuration file according to a set algorithm. Use TEST_CONFIG() macro to incorporate error checking.
G_debug
	Global symbol exported by the library that enables debug output from the library if set to 1.
G_rundir
	Global symbol exported by the library that is set by Read_my_dir() that can be used for keeping track of the runtime directory.
G_runtarget
	Global symbol exported by the library that is set by Read_my_target() that can be used for keeping track of the runtime executable filename.
Hash_add()
	Add new data item to hash table.
Hash_del()
	Delete data item from a hash table.
Hash_find()
	Find data item in a hash table.
Hash_free()
	Free memory previously claimed by a hash table.
Hash_init()
	Initialises a hash table. In order to display error messages correctly, run Error_init() before calling this routine, and use the functions Error() or Error1() to report error messages. This function is actually implemented as a macro so that the 7th argument can be discarded if the library was not compiled following a configure --enable-extradebug.
Hash_runfunc()
	Traverse a hash running a user supplied function on every data item.
Hash_settype()
	Set type of hash table to HTYPE_UNIQUE or HTYPE_FORCEUNIQUE. This involves setting the type on every bucket.
Read_my_dir()
	Reads path or filename passed in string (usually from argv[0]), and calculates directory in which the filename resides using PATH variable if necessary, storing pointer to directory name in the global variable G_rundir which can then be referenced by other functions at any time.
Read_my_target()
	Reads path or filename passed in string (usually from argv[0]), and stores pointer to the basename in the global variable G_runtarget which can then be referenced by other functions at any time.
Setchrcmp()
	Compares character with a set of characters in a given string. If the character is found in the set, a pointer is returned to the character in the set that matched.
Setcount()
	Counts the number of occurrences of all characters listed in a set of characters.
Setrchr()
	Searches given string backwards, looking for the first character that does not match one of those in the given list of characters, returning a pointer to the character immediately following this.
Slist_add()
	Add new data to a single linked list.
Slist_del()
	Delete data from a single linked list.
Slist_find()
	Find data in a single linked list.
Slist_free()
	Free memory previously claimed by single linked list structure.
Slist_init()
	Initialises a single linked list structure. In order to display error messages correctly, run Error_init() before calling this routine, and use the functions Error() or Error1() to report error messages. This function is actually implemented as a macro so that the 4th argument can be discarded if the library was not compiled following a configure --enable-extradebug.
Slist_runfunc()
	Traverse a single linked list running a user supplied function on each data item.
Stack_flush()
	Empty the stack. If the result of the flush leaves enough empty space in the dynamic array to warrant shrinking the array, then a shrink will occur.
Stack_free()
	Free memory previously claimed by a stack structure.
Stack_init()
	Initialises a data stack structure, implemented in a dynamic array (vector). In order to display error messages correctly, run Error_init() before calling this routine, and use the functions Error() or Error1() to report error messages. This function is actually implemented as a macro so that the 6th argument can be discarded if the library was not compiled following a configure --enable-extradebug.
Stack_pull()
	Pull data off the stack. If the result of the pull leaves enough empty space in the dynamic array to warrant shrinking the array, then a shrink will occur.
Stack_push()
	Push data item onto the stack. Grow the dynamic array to accommodate new data if required.
Strdup()
	Copies a string to a new area of memory, just like strdup(), except that a maximum number of characters to copy can be specified.
Strdup_noprot()
	Copies a string to a new area of memory, just like strdup(), except that characters protected by a backslash are unprotected (by removing the backslash) if the protected character matches one of a set of characters.
Strdup_nochar()
	Copies a string to a new area of memory, just like strdup(), except that characters in the provided set of characters are stripped out of the resulting string.
Strcatsave()
	Takes source string and concatenates onto the end of the destination string, much like strcat(), except the result is stored in a new area of memory claimed using malloc() or realloc().
Vector_free()
	Free memory previously claimed by a dynamic array structure. While calling this function serves no purpose for a VTYPE_UCHAR1 array, doing so will cause no harmful side effects.
Vector_grow()
	Expand dynamic array, the array is guaranteed to be filled with zeroes where it is expanded. Use the Vector_growtest() macro first to see if the vector actually needs to be expanded in size.
Vector_init()
	Initialises a dynamic array (vector) structure, the array is guaranteed to be filled with zeroes upon initialisation. In order to display error messages correctly, run Error_init() before calling this routine, and use the functions Error() or Error1() to report error messages. This function is actually implemented as a macro. Use the Vector_init1() macro to initialise an unsigned char array with a user-supplied array that already exists. This allows existing binary data to be accessed through the vector APIs, but will not permit growing or shrinking of the array.
Vector_shrink()
	Shrink dynamic array. Use the Vector_shrinktest() macro first to see if anything will be gained by shrinking.

dl_size_t
	Number of elements in a double linked list.
hash_bkt_t
	Number of buckets in a hash table.
hash_key_t
	Hash key.
hash_size_t
	Number of data elements in the entire hash table.
sl_size_t
	Number of elements in a single linked list.
stack_size_t
	Number of elements pushed onto a stack.
vector_size_t
	Number of elements in a vector.

dlist_element
	Structure encapsulating a data item within a double linked list.
dlist_root
	Root structure defining a double linked list.
errcode
	Structure containing error code and error message.
hash_table
	Root structure defining a hash table.
slist_element
	Structure encapsulating a data item within a single linked list.
slist_root
	Root structure defining a single linked list.
stack_data
	Union for a stack data item of either a pointer, uchar_t or ulong_t.
stack_root
	Root structure defining a stack.
vector_root
	Root structure defining a dynamic array (vector).

COPY_STRING()
	Shortcut for strdup() with error checking.
Dlist_settype()
	Set type of double linked list to DL_TYPE_UNIQUE, DL_TYPE_NONUNIQUE or DL_TYPE_FORCEUNIQUE.
Dlist_size()
	Return number of elements in a double linked list.
Hash_belem()
	Return number of elements in a specified bucket and hash table.
Hash_nbuckets()
	Return number of buckets in a hash table (used or unused).
Hash_nelem()
	Return number of elements in a hash table (all buckets).
Hash_nused()
	Return number of used buckets in a hash table.
MALLOC_CHECK()
	Shortcut for malloc() with error checking.
PANIC()	Display message and exit abruptly. Not a clean exit, should not be used to handle runtime error messages that may occur in production environments.
REALLOC_CHECK()
	Shortcut for realloc() with error checking.
Slist_settype()
	Set type of single linked list to SL_TYPE_UNIQUE, SL_TYPE_NONUNIQUE or SL_TYPE_FORCEUNIQUE.
Slist_size()
	Return number of elements in a single linked list.
Stack_get()
	Return entire stack structure as a vector. This is chiefly used if the stack needs to be treated as a queue instead. The data must not be changed, however, outside of the stack APIs.
Stack_peek()
	Peek at data item on top of the stack without pulling.
Stack_size()
	Return number of data items that have been pushed onto the stack.
Stack_type()
	Return type of stack, one of STYPE_POINTER, STYPE_UCHAR or STYPE_ULONG.
TEST_CONFIG()
	Shortcut for Find_my_config() with error checking.
Vector_growtest()
	Test to see if a vector needs to grow to accommodate more data. This macro does not make any changes to the vector.
Vector_paddr()
	Lookup a pointer element in a vector of type VTYPE_POINTER.Thismacroisalsousedforaddingdatatothevector.
Vector_ptop()
	Return first pointer element in a vector of type VTYPE_POINTER.
Vector_size()
	Return last element used in a vector. This macro must also be used to keep the size of the vector up to date. The API cannot keep track of vector usage, and if the size is not kept current then Vector_growtest() and Vector_shrinktest() will not work.
Vector_shrinktest()
	Test to see if the vector can be shrunk in size. This macro does not make any changes to the vector.
Vector_type()
	Return type of vector, one of VTYPE_POINTER, VTYPE_UCHAR, VTYPE_UCHAR1 or VTYPE_ULONG.
Vector_ucaddr()
	Lookup an unsigned char element in a vector of type VTYPE_UCHAR or VTYPE_UCHAR1.Thismacroisalsousedforaddingdatatothevector.
Vector_uctop()
	Return first uchar_t element in a vector of type VTYPE_UCHAR or VTYPE_UCHAR1.
Vector_uladdr()
	Lookup an unsigned long element in a vector of type VTYPE_ULONG.Thismacroisalsousedforaddingdatatothevector.
Vector_ultop()
	Return first ulong_t element in a vector of type VTYPE_ULONG.

CAST_DLSIZE
	Type to cast to in order to use printf() on a dl_size_t with the FMT_DLSIZE or FMT_XDLSIZE format codes.
CAST_DYNSIZE
	Type to cast to in order to use printf() on a vector_size_t with the FMT_DYNSIZE or FMT_XDYNSIZE format codes.
CAST_HBSIZE
	Type to cast to in order to use printf() on a hash_bkt_t with the FMT_HBSIZE or FMT_XHBSIZE format codes.
CAST_SLSIZE
	Type to cast to in order to use printf() on a sl_size_t with the FMT_SLSIZE or FMT_XSLSIZE format codes.
DEFILE	File name of this source code for debug messages.
DELINE	Current line number in this source code for debug messages.
DL_TYPE_UNIQUE
	Type of double linked list used to keep entries unique, silently dropping duplicates.
DL_TYPE_NONUNIQUE
	Type of double linked list used to permit duplicate entries.
DL_TYPE_FORCEUNIQUE
	Type of double linked list used to force an E_ALREADY error on duplicate entries.
ERR_CUSTOM_FIRST
	First custom error code used by the library.
ERR_CUSTOM_LAST
	Highest custom error code that may be used by the library.
ERR_CUSTOM_MAX
	Total number of custom error codes that may be used by the library.
FMT_DLSIZE
	Format code for printf() used for printing the decimal value of a dl_size_t.
FMT_DYNSIZE
	Format code for printf() used for printing the decimal value of a vector_size_t.
FMT_SLSIZE
	Format code for printf() used for printing the decimal value of a sl_size_t.
FMT_HBSIZE
	Format code for printf() used for printing the decimal value of a hash_bkt_t.
FMT_XDLSIZE
	Same as FMT_DLSIZE except for printing the value in hexadecimal.
FMT_XDYNSIZE
	Same as FMT_DYNSIZE except for printing the value in hexadecimal.
FMT_XSLSIZE
	Same as FMT_SLSIZE except for printing the value in hexadecimal.
FMT_XHBSIZE
	Same as FMT_HBSIZE except for printing the value in hexadecimal.
HTYPE_UNIQUE
	Type of hash table where identical entries are silently dropped.
HTYPE_FORCEUNIQUE
	Type of hash table where identical entries cause an E_ALREADY error.
MAX_DLIST
	A double linked list cannot support more elements than this.
MAX_HASH_BUCKETS
	A hash table cannot support more buckets than this.
MAX_HASH_ELEMENTS
	A hash table cannot support more elements than this.
MAX_SLIST
	A single linked list cannot support more elements than this.
MAX_VECTOR
	A dynamic array (vector) cannot support more elements than this.
SL_TYPE_UNIQUE
	Type of single linked list used to keep entries unique, silently dropping duplicates.
SL_TYPE_NONUNIQUE
	Type of single linked list used to permit duplicate entries.
SL_TYPE_FORCEUNIQUE
	Type of single linked list used to force an E_ALREADY error on duplicate entries.
STYPE_POINTER
	Type of stack holding pointers.
STYPE_UCHAR
	Type of stack holding unsigned chars.
STYPE_ULONG
	Type of stack holding unsigned longs.
VTYPE_POINTER
	Type of vector holding pointers.
VTYPE_UCHAR
	Type of vector holding unsigned chars.
VTYPE_UCHAR1
	A user-supplied vector holding unsigned chars (not dynamic).
VTYPE_ULONG
	Type of vector holding unsigned longs.

E_NOSPACE
	No space left.
E_LIST_NOSPACE
	No space left in linked list.
E_HASH_NOSPACE
	No space left in hash table.
E_STACK_NOSPACE
	No space left in stack.
E_VECTOR_NOSPACE
	No space left in vector.
E_ALREADY
	Entry already exists.

libIvor.so.

PROSE Programming Language at prose.sourceforge.net,
GNU Automake & Autoconf at www.gnu.org.

Copyright (c) 2002, 2003, 2004 Mark R. Bannister <cambridge@users.sourceforge.net>.

This is free software and can be downloaded from prose.sourceforge.net; see the source for copying conditions. There is NO warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.