Table Of Contents
About Nilorea Library
Nilorea is a portable C utility library providing a broad set of tools for systems programming, networking, game development, and more. It can be used as a collection of individual .c/.h files or built as a shared library (.so / .dll).
The library covers logging, dynamic strings, linked lists, hash tables, stacks, trees, thread pools, TCP/UDP networking with optional SSL/TLS, message serialization, configuration file parsing, regex matching, cryptography, pathfinding, fluid simulation, isometric tile engines, GUI widgets, and particle systems.
The name comes from one of the author's earliest projects: an unfinished game that gave birth to a reusable library. The opposite may happen one of these days.
See the API Overview section for detailed API documentation of each component.
API Overview
The library is organized into the following module categories:
| Category | Modules |
| Core & Utilities | COMMONS: macros, headers, defines, timers, allocators,..., LOGGING: logging to console, to file, to syslog, to event log, LOGGING NODUP: no duplicate logging to console, to file, to syslog, SIGNALS: signals handling and stack printing, ENUMERATIONS: quick and clean enum macro set, EXCEPTIONS: C++ style try,catch,endtry,throw, FILES: files utilies |
| Data Structures | LISTS: generic type list, HASH TABLES: classic or trie tree hash_tables, STACKS: generic type stack, TREE: various tree with generic support |
| Strings & Cyphers | STRINGS: replacement to char *strings with dynamic resizing and boundary checking, CYPHERS: BASE64 (encode / decode) (from / to) a N_STR *string, CYPHERS: VIGENERE (encode / decode) a (N_STR / file) with a root key or a combination of a question and an answer, ZLIB: shortcuts to easy compress/decompress data |
| Networking | NETWORK ENGINE: connect, accept, send and recv wrappers. Network Queue, thread-safe add/get message, ssl/tls secured communications, NETWORK MESSAGES: tools to serialize integers, double, N_STR from and back to a single N_STR *message, ACCEPT_POOL: parallel accept pool for high-performance connection handling, NETWORK USERS: server side network oriented user handling, CLOCK_SYNC: client/server clock offset estimation |
| Threading & Timers | THREADS: tools to create and manage a thread pool, TIMERS: generally used headers, defines, timers, allocators,... |
| Game & Simulation | PHYSICS: simple 3D movement simulation, AABB3D: simple space area management API, ASTAR: A* pathfinding for 2D/3D grids, DEAD_RECKONING: latency hiding with extrapolation and convergence blending, TRAJECTORY: cubic Hermite spline dead reckoning and movement simulation for 2D/3D, FLUIDS: fluid simulation example, GAME APPS: game environment management utilities, GRAPHICS: isometric engine, maps, tiles, ... |
| Graphics (Allegro 5) | ALLEGRO5: allegro 5 helpers (user input,...), GRAPHICS: animation library, loading structures and blit funcs, GRAPHICS: 3D particles utilities, GUI: allegro5 widget system with pseudo-windows |
| Data Interchange | AVRO: binary format encoding/decoding with JSON conversion |
| Optional Integrations | PCREs: regex matching helpers, CONFIGURATIONS: classic config file loading/saving, KAFKA: generic event producer and consumer functions, GIT: libgit2 wrapper for repository operations |
Core & Utility Modules
- COMMONS: macros, headers, defines, timers, allocators,... — Common macros, headers, defines, timers, memory allocators, process daemonization, and environment utilities. The foundation included by most other modules.
- LOGGING: logging to console, to file, to syslog, to event log — Configurable logging system supporting output to console, files, syslog (Linux), and Windows event log. Supports multiple log levels (DEBUG, INFO, NOTICE, ERROR, etc.).
- LOGGING NODUP: no duplicate logging to console, to file, to syslog — No-duplicate logging extension. Filters repeated log messages using an internal hash table so each unique message is emitted only once per session.
- SIGNALS: signals handling and stack printing — Signal handling and stack trace printing. Installs backtrace handlers for crash diagnostics.
- ENUMERATIONS: quick and clean enum macro set — Macro system to define enumerations together with their automatic to-string conversion functions. Based on a reduced version of SmartEnum.
- EXCEPTIONS: C++ style try,catch,endtry,throw — C++ style exception handling for C using try/catch/throw semantics built on setjmp/longjmp.
- FILES: files utilies — File system utilities: directory scanning, file information retrieval, and helper functions for file operations.
Data Structure Modules
String & Cypher Modules
- STRINGS: replacement to char *strings with dynamic resizing and boundary checking — Dynamic string type (N_STR) replacing raw char* with automatic resizing and boundary checking. Provides creation, duplication, concatenation, printf-style formatting (nstrprintf), trimming, search/replace, case conversion, tokenization, and file I/O. The core string type used throughout the library.
- CYPHERS: BASE64 (encode / decode) (from / to) a N_STR *string — Base64 encoding and decoding operating on N_STR strings.
- CYPHERS: VIGENERE (encode / decode) a (N_STR / file) with a root key or a combination of a question and an answer — Vigenere cipher for encoding/decoding N_STR strings and files. Supports root key, question/answer key derivation, and quick encode/decode with auto-generated keys.
- ZLIB: shortcuts to easy compress/decompress data — Compression and decompression shortcuts using zlib, operating on N_STR strings.
Network Modules
- NETWORK ENGINE: connect, accept, send and recv wrappers. Network Queue, thread-safe add/get message, ssl/tls secured communications — Full-featured network engine for TCP and UDP. Provides connection management, accept/connect wrappers, send/recv with buffering, a thread-safe network message queue, and optional SSL/TLS encrypted communications via OpenSSL. Supports both client and server modes. Includes HTTP CONNECT and HTTPS CONNECT proxy tunneling (with TLS to the proxy), SOCKS5 proxy tunneling, WebSocket client handshake and framing, and Server-Sent Events (SSE) client support. All network error paths capture messages into a per-connection ring buffer retrievable via n_netw_get_error() / n_netw_get_connect_error(). See
SSL_SECURITY.md for a security audit and the ex_network_ssl_hardened example for TLS 1.2+ enforcement, strong cipher suites, security headers (HSTS, CSP, X-Frame-Options), path traversal protection, and connection timeouts.
- NETWORK MESSAGES: tools to serialize integers, double, N_STR from and back to a single N_STR *message — Message serialization and deserialization tools. Pack integers, doubles, and N_STR strings into a single N_STR message for network transmission. Includes ready-made message types for ping, identification, position updates, string messages, and quit signals. Handles byte order conversion for cross-platform compatibility.
- ACCEPT_POOL: parallel accept pool for high-performance connection handling — Parallel accept pool for high-performance connection handling (nginx-style). Multiple threads call accept() on a shared listening socket and invoke a user callback for each connection. Supports three server architectures: single-inline (serialized accept+handle), single-pool (serialized accept, parallel handling via thread pool), and pooled (parallel accept and handling). The pooled mode benefits scenarios with high connection rates over real networks, SSL/TLS handshakes in the accept path, or multi-socket NUMA systems. See the mode comparison for guidance on choosing the right architecture.
- NETWORK USERS: server side network oriented user handling — Server-side user management for networked applications. Tracks connected users with their associated network connections, supports per-user message queues, broadcast/unicast messaging, and position recording.
- CLOCK_SYNC: client/server clock offset estimation — Clock synchronization estimator for networked games. Estimates the time offset between a local clock and a remote clock using periodic sync request/response pairs. Uses a median filter over recent samples to reject outliers caused by network jitter.
Threading & Timer Modules
Game & Simulation Modules
- PHYSICS: simple 3D movement simulation — Simple 3D movement simulation with position, velocity, and acceleration vectors.
- AABB3D: simple space area management API — Axis-Aligned Bounding Box (AABB) management for 3D space partitioning and collision detection.
- ASTAR: A* pathfinding for 2D/3D grids — A* pathfinding algorithm for 2D and 3D grid-based maps. Supports customizable heuristics and movement costs.
- DEAD_RECKONING: latency hiding with extrapolation and convergence blending — Dead reckoning for latency hiding in networked games. Uses extrapolation and convergence blending to smooth remote entity movement.
- TRAJECTORY: cubic Hermite spline dead reckoning and movement simulation for 2D/3D — Cubic Hermite spline interpolation for dead reckoning and movement simulation in 2D/3D networked environments.
- FLUIDS: fluid simulation example — Eulerian fluid simulation. A port of "How to write an Eulerian fluid simulator with 200 lines of code" by Ten Minute Physics.
- GAME APPS: game environment management utilities — Game environment management utilities for application setup and lifecycle.
- GRAPHICS: isometric engine, maps, tiles, ... — Isometric/axonometric tile engine with height maps, per-tile height segments (bridges, floating structures), configurable axonometric projections (classic, isometric, military, staggered), terrain transition bitmasks (edge + corner), depth-sorted object rendering with occlusion detection and clipped transparent overlay, 2D camera with zoom/scroll/follow, segment-sorted draw order, height border edge visibility, and chunk-based binary map save/load.
Graphics Modules (Allegro 5)
These modules require the Allegro 5 library and are only compiled when Allegro 5 is detected (or can be excluded with FORCE_NO_ALLEGRO=1):
- ALLEGRO5: allegro 5 helpers (user input,...) — Allegro 5 helper functions for user input handling and display management.
- GRAPHICS: animation library, loading structures and blit funcs — Animation library providing sprite loading, animation parameter management, and blit functions.
- GRAPHICS: 3D particles utilities — 3D particle system utilities for visual effects.
- GUI: allegro5 widget system with pseudo-windows — Widget system built on Allegro 5, providing buttons, sliders (with configurable step, mouse scroll, and keyboard support), text areas, checkboxes, scrollbars, listboxes, radio lists (with clear/reset), combo boxes (auto-scroll to selected item on open, optional auto-width), dropdown menus (with scrollbar), labels, images, and pseudo-window management with z-order support (always-on-top, always-behind, fixed z-value), frameless windows, auto-scrollbar windows, resizable windows, and disabled/hidden widget states. Adaptive window resize with per-window policies (none / move / scale) alongside the existing virtual canvas scaling. All scrollable widgets use unified thumb-aware scrollbar positioning with click-and-drag support. Tab/Shift+Tab focus navigation cycles between widgets. Arrow keys, Home, and End provide keyboard control for sliders, lists, scrollbars, and checkboxes. Global and focused key bindings for buttons (focused bindings fire only when specific source widgets have focus). Text dimensions use al_get_text_dimensions for accurate bounding-box measurement.
Data Interchange Modules
- AVRO: binary format encoding/decoding with JSON conversion — Avro binary format encoding and decoding with JSON conversion. Implements the Avro specification from scratch (zig-zag varint, IEEE 754 floats, Object Container File format with magic bytes, metadata, sync markers, data blocks). Supports all Avro types: null, boolean, int, long, float, double, bytes, string, record, enum, array, map, union, fixed. Provides file-level (JSON file + schema file → Avro file and back), in-memory container (cJSON + AVRO_SCHEMA → N_STR), and N_STR-based (schema N_STR + JSON N_STR → Avro N_STR) conversion APIs. (Requires: cJSON)
Optional Integration Modules
These modules are compiled only when their respective dependencies are detected:
- PCREs: regex matching helpers — PCRE2 regex matching helpers. Provides simplified wrappers around the PCRE2 library for pattern matching operations. Required by the configuration file and Kafka modules. (Requires: libpcre2-8)
- CONFIGURATIONS: classic config file loading/saving — Configuration file loading and saving using a classic key=value format with section support. Parses config files into hash table structures for easy access. (Requires: PCRE)
- KAFKA: generic event producer and consumer functions — Apache Kafka event producer and consumer integration. Generic functions for producing and consuming Kafka messages with configuration support. (Requires: librdkafka, PCRE, cJSON, OpenSSL)
- GIT: libgit2 wrapper for repository operations — Git repository operations via libgit2. Open, init, and close repositories; stage, unstage, and commit files; retrieve commit logs and diffs; checkout paths or commits; create, switch, list, and delete branches; push and pull with remote authentication (token, basic, SSH). (Requires: libgit2)
Requirements
Core library (no optional dependencies):
- GCC with C17 support (gnu17)
- POSIX threads (pthread)
- zlib (compression)
- Standard math library
For SSL/TLS network encryption:
- OpenSSL (libssl, libcrypto)
For regex and configuration file support:
- PCRE2 library (libpcre2-8)
For graphical/audio modules:
For Git repository operations:
For Kafka integration:
- librdkafka (bundled as git subtree in external/librdkafka)
- cJSON (bundled as git subtree in external/cJSON)
- OpenSSL
- PCRE2
- libsasl2
Platform-specific:
- Linux: standard POSIX environment
- Windows: MinGW (32 or 64-bit), Winsock2
- SunOS/Solaris: socket, nsl, rt libraries
Build Flags
The build system auto-detects available optional dependencies. You can force-disable specific features using environment variables:
| Flag | Effect |
| FORCE_NO_ALLEGRO=1 | Disable Allegro 5 graphics modules |
| FORCE_NO_OPENSSL=1 | Disable OpenSSL/TLS support |
| FORCE_NO_KAFKA=1 | Disable Kafka integration |
| FORCE_NO_PCRE=1 | Disable PCRE2 regex and config file support |
| FORCE_NO_CJSON=1 | Disable cJSON support |
| FORCE_NO_LIBGIT2=1 | Disable libgit2 Git operations |
| DEBUG=1 | Enable debug build with sanitizers |
| DEBUG_THREADS=1 | Use ThreadSanitizer instead of AddressSanitizer (with DEBUG=1) |
| ALL_AS_ERROR=1 | Treat all warnings as errors (with DEBUG=1) |
LeakSanitizer suppressions for GPU/display drivers:
GPU drivers (Mesa, DRM, X11) may report small fixed-size leaks via LeakSanitizer in DEBUG=1 builds. These are not caused by Nilorea code. Suppress them with:
LSAN_OPTIONS=suppressions=examples/lsan-suppressions.cfg ./examples/ex_gui
Installation
Build the library:
make # auto-detects dependencies and builds static + shared library
make DEBUG=1 # debug build with AddressSanitizer and UndefinedBehaviorSanitizer
make all # build library and all examples
make doc # generate this documentation with Doxygen
make show-detected-option #
display which optional dependencies were found
ALLEGRO_DISPLAY * display
For Kafka support, first build the bundled librdkafka:
make integrate-deps # build and integrate external dependencies
Link against the library:
gcc your_code.c -I/path/to/include -L/path/to/lib -lnilorea -lpthread -lm -lz
Add optional link flags as needed: -lssl -lcrypto (OpenSSL), -lpcre2-8 (PCRE2), -lallegro ... (Allegro 5).
Closing Words
Nilorea is a "make life easier" library. You are welcome to use it.
Everything inside is licensed under the GNU General Public License v3.0 or later. Read it at https://www.gnu.org/licenses/gpl-3.0.html
You can reach the author at coder at nilorea.net
More information on the website: https://www.nilorea.net
1.9.8