libmba <mba/*.h>
The libmba package is a collection of mostly independent C modules potentially useful to any project. There are hashmap, linkedlist, pool, and stack ADTs, a CSV parser, a DOM-like interface for simple XML processing, a module for managing error codes and associated messages across separate C libraries, and more.
Cfg
The cfg(3m) module provides an interface to load and store comments and key/value pairs. A small state machine parser preserves all space tokens and comments in order between loading, manipulating, and storing cfg files. The following is a sample of serialized properties (the cfg file format):
# This is a comment
addr = 192.168.1.15
!port = 15000
user.1 = miallen
user.2 = gchan
Lines beginning with the '#' and '!' characters will be interpreted as comments. Keys are separated from values with '='. String encoding is locale dependant.
Csv
The csv(3m) module parses the popular comma separated values (CSV) format exported by applications like spreadsheets.
Domnode
The domnode(3m) module provides a lightweight DOM-like interface for manipulating XML documents as a tree of nodes in memory. Functions are provided to load and store XML sources to and from trees of domnode structures. It follows the "everything is a node philosophy". Four different node types are supported; element, attribute, text, and comment. The linkedlist(3m) functions are used to modify the children and attributes of a node.
Eval
The eval(3m) module will evaluate simple arithmentic expressions consisting of integers, symbols for which the provided symlook_fn returns an integer, and any of the operators |&^+-*/(). Operator precedence is roughly the same as the C language; '(' and ')' are higher than '*' and '/' which are higher than '+' and '-' which are higher than '^', '&', and '|'. Prefixing integer tokens with '-' to indicate negative values is currently not supported.
Hashmap
A hashmap(3m) object associates keys with pointers to data
objects. Large numbers of elements may be stored and retrieved efficiently.
It is vital that the free_key_fn and free_data_fn
parameters are correct. If memory management of all keys and data is
handled externally from the hashmap both function pointers must be
NULL. There is only one appropriate pair of parameters for each
scenario. Choosing incorrectly will result in a memory leak or undefined
behavior.
Keys are only compared by their hash values. Keys that collide during a put
will first be remove and called with free_key_fn on the existing
key and free_data_fn on it's data pointer. For this reason hash
functions must be chosen carefully. Please note, the hash_string
function can return the same hash value for different strings in rare cases
(e.g. the two character strings 'X"' and 'WA' both hash to the value 2762).
Hexdump
The hexdump(3m) module provides useful debugging functions for printing the contents of memory in standard hex dump format.
Linkedlist
The linkedlist functions manipulate a sigularly linked list of data pointers.
The struct linkedlist * parameter represeting the list being operated on must be valid. If a the list parameter is a null pointer, a null pointer or -1 will be returned and errno will be set to EINVAL.
Mbs
The mbs(3m) module provides extended string functions that will work with the locale dependant encoding such as UTF-8 or any 8 bit encoding. They are useful for determining complete substrings of UTF-8 sequences such as when terminal output must consider the number of display positions that a sequence of characters will occupy. More generally, the objective of this function is to emulate the behavior of non-multibyte Unicode string manipulation like that of UTF-16 and JAVA encodings although such behavior has not been verified.
Please note some of these functions are not actively used by the author. They have been tested but should be considered experimental and may be subject to change or removal.
Msgno
The msgno(3m) module provides a mechanism for managing error codes (or more generically message numbers) and associated messages across separate C libraries. This is very similar to the com_err library but with runtime message registration and stack-trace-like output.
Each participating library registers a table of messages at runtime with the msgno_add_codes function. Several macros are provided to dispatch messages (e.g. print to stderr). When a library is compiled with other packages that use also use msgno and GNU cpp is used (for variatic macros), the following stack trace like output may be generated:
src/expatls.c:97:utf8tods: Character encoding error
src/expatls.c:449:start_fn:
src/dom.c:405:DOM_Element_normalize:
dump.c:30:main: Failed to process sample.xml
The MSGNO macro must be set to activate msgno(3m). Currently the GNU C preprocessor(cpp) is required to support full stack-trace-like output because of the variatic macros used by this package. Note currently this code is not reentrant. A future version will accept a context object or arbitrary buffer to enable the module to be used in a threaded environment.
Pool
The pool(3m) module provides a container that will manage a reuseable pool of data objects. If the data objects are costly to create (e.g. a database connection) and can be reused in a different context the object can be released back to the pool for retrival at a later point without creating and destroying objects frequently. The number of data objects in a pool is limited to POOL_SIZE_MAX defined in the pool(3m) header file. This limit is 2040 by default which will create a bitmap of 256 bytes. Memory to store data pointers will increase dynamically as more space is required.
Shellout
The shellout(3m) module provides a robust interface to a UNIX shell such as sh or bash. Spawned programs may be controlled interactively from a terminal (i.e. "shell out") or entirely in the background (i.e. cron, network daemon, etc). For most purposes this functionality is identical to that of the popular expect(1) program.
Stack
The stack functions manipulate a simple LIFO stack of pointers to objects but the underlying array will grow and shrink as storage requirements change.
Text
The text module provides typedefs and macros to abstract the character type and all standard library functions that operate on them. The resulting source code will support extended charsets and can be used with little or no modification on a variety of popular platforms. If USE_WCHAR is defined, wide characters will be used (e.g. wchar_t is UTF-16LE on Windows). Otherwise the locale dependent encoding will be used (e.g. UTF-8 on Unix). Many functions in libmba now accept tchar * strings however char * or wchar_t * strings can be used with these functions as tchar is just a typedef for unsigned char or wchar_t.
Additionally, several sentinel pointer string functions are provided.
See Tchar I18N Text Abstraction for details.
Varray
The varray(3m) module is a variable array that permits quick access to elements by index without allocating all the memory for the array when the array is created. Instead, memory is allocated as necessary in increasingly larger chunks (32 * membsize, 64 * membsize, 128 * membsize, ... upto 2^21 * membsize).