qLibc: one C API for hash tables, trees, vectors and queues

What qLibc is, and the licence question the badges do not settle

qLibc describes itself as a simple and yet powerful C library providing generic data structures and algorithms, and the README goes further, calling it one of the most functionally-complete, publicly-licensed C/C++ libraries, with the goal of providing a simple and powerful general purpose C/C++ library that includes all kinds of containers and general library routines. The stated reason for existing is consistency, that it provides a ready-made set of common container APIs with a consistent API look. The licence needs a careful reading. The README says qLibc is published under the 2-clause BSD licence, also known as the Simplified BSD Licence, and to refer to the LICENSE document included in the package for details, while the licence field in the repository is recorded as a custom one that GitHub cannot classify. The two statements are not necessarily in conflict, since a modified BSD header is exactly the kind of thing GitHub's classifier rejects, but the practical instruction is to read the LICENSE file rather than the badge. The primary language is C, the homepage is wolkykim.github.io/qlibc, and the last push to the repository was on 2026-08-11.

Installation is the standard GNU build, and the language floor is stated

qLibc uses GNU AutoTools as the primary tool for compilation, and the README says to execute a short sequence in the main directory of the project, which is configure, then make, then sudo make install. The language requirement is given as at least GNU99, and the project says it is confirmed to be compiling in GNU23. The presence of both configure.ac and config.h.in alongside a CMakeLists.txt in the repository means there is a second build path for people who do not want Autotools, which matters more for a library that gets vendored into other projects than it would for an application. The repository also carries a Makefile.in, an install-sh script, config.guess and config.sub, an INSTALL.md, and directories for include/, lib/, src/, tests/, examples/ and doc/. The primary language is C with the description naming C/C++.

./configure
make
sudo make install

The four key/value tables, and how they differ

The container set divides into tables for key/value pairs and containers for objects, and the tables come in four flavours with genuinely different characteristics. The Tree Table is a binary tree, specifically a left-leaning red-black tree, with O(log n) search, insert and delete, keys stored sorted, a user comparator supported, no duplicated keys, and a nearest key search. The Hash Table is hash-based with O(1) or O(n) operations, keys not stored sorted, and a user comparator not supported. The Static Hash Table is fixed size memory, using an array, mmapped or shared memory, with pre-allocation, keys stored digested, no comparator, and it is the only table that can use shared memory. The List Table is a doubly linked list with O(n) search and O(1) insert, and it is the only one that supports duplicated keys and an option for keys stored sorted. All four support iterator support, and thread safety is an option on three of them.

The tables at a glance, and the row that decides your choice

The characteristic table is the most useful thing in the README, and one row decides most selections. The Space allocation row reads Dynamic for the tree table, the hash table and the list table, and Pre-allocation for the static hash table. Everything else follows from that single difference, because a pre-allocated table has a known size and a known memory footprint, which is what you want in an embedded or shared memory setting, while the other three grow as you insert. The Key stored digested row also separates the static hash table from the rest, since it stores digests rather than the keys themselves, which bounds the memory the key material occupies but means you cannot recover a key from the table. The Iterator visit order row is the other useful one, min to max for the tree table, random for both hash tables and insert order for the list table.

The consistent API, and the one-line swap that demonstrates it

The Consistent API Look section explains the central idea. All container APIs have a consistent look and feel, with a creator function that usually returns a pointer to a container structure, and all functions related to the container can be accessed through function pointers inside the container or through traditional direct-access APIs. The examples make the point concretely. You create a hash table with qhashtbl and a flags argument, put an element with a key and a pointer to the value and its size, get it back with tbl->get, print it, free it, and release the table with tbl->free. The linked-list-table version is identical, and the only change is one line, the container creation. The README says so directly, that there are not any code changes at all except for 1 line in the table creation, which is why qLibc encapsulates corresponding function pointers inside the container object. The trade is the one every generic interface has, and the direct APIs are the escape hatch when the indirection costs you.

// create a hash-table.
qhashtbl_t *tbl = qhashtbl(0, QHASHTBL_THREADSAFE);

// add an element whose key is "score".
int x = 12345;
tbl->put(tbl, "score", &x, sizeof(int));

// get the value of the element.
int *px = tbl->get(tbl, "score", NULL, true);
if(px != NULL) {
  printf("%d\n", *px);
  free(px);
}

// release table
tbl->free(tbl);

The general utilities and the extension library

The API reference splits into a core reference and an extension reference, and the split is a reasonable one because the extensions pull in heavier dependencies. The core covers the key/value containers and the object containers, which are a doubly linked list, a vector implementing a growable array of elements, a FIFO queue and a LIFO stack. Then the general utilities, grouped as strings with a trimmer, modifier, replacer, case converter and pattern detectors, I/O with non-blocking support and stream reader and writer, files with locking, a directory handler and path correctors, IPC with semaphores and shared memory, encoders and decoders for URL and Base64 and Hex, hashes with Murmur, FNV and MD5, and time with difference and format conversion. The extension library adds an Apache-style configuration file parser, an INI-style one, an HTTP client, a rotating file logger, a MySQL database interface, and a token bucket implementation.

The examples directory, which is the fastest way to learn the API

The examples directory is organised one program per container, and it doubles as the library's documentation. There are files for the Apache configuration parser, for the config parser itself, for a growable structure with both a plain and an object variant, for a hash array, for the hash table, for a list, for the list table, for the queue, for the stack and for the vector, most with a matching.out file alongside the source, so the expected output is checked in beside the code that produces it. That pairing is a good sign about how the project treats its own semantics, because a container library's behaviour is mostly in the edges and a checked-in expected output pins those down. The Makefile.in in that directory and the tests/ directory at the root mean the examples are part of the build rather than a separate thing, and the CI workflow badge is the Actions status for the repository.

What the project needs, and where it stands

The Looking for people to work with section names the three areas with high demand, and they are an honest signal about the state of the project. Automated testing is the first, documentation the second, and new feature implementation the third. For a library that claims functional completeness, an explicit request for help with automated testing tells you the test coverage is thinner than the feature list, which is exactly the thing to weigh before depending on it for a system where a container bug matters. The contributors list names the project lead, Seungyoung Steve Kim, followed by around twenty others in alphabetical order by first name, with an invitation to say so if a name is missing or misspelled. The releases are v2.4.8 from November 2022, v2.5.0 from July 2023 and v2.5.1 from April 2026, so the 2.5 line has been in place for a while and the recent release restored a version that had been quiet.

Editorial conclusion

qLibc suits a C or C++ project that wants a batteries-included standard library with consistent containers, and that would like to choose a hash table or a tree at a point where the data volume justifies it, which is a choice the standard library never offers. It is the wrong choice if you need a small dependency footprint, because this is a whole library rather than a single header, and a poor fit if you need containers that are safe under concurrent use without configuring them, since thread safety is a per-container option rather than the default. Before adopting it, read the tables at a glance, because the static hash table is the one that behaves differently in every dimension, and note that the library is published under the two-clause BSD licence while the GitHub licence field is listed as unclassifiable, so read the LICENSE document in the package.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. wolkykim/qlibc on GitHub