Logcie

Logcie is a lightweight, single-header logging library for C with a modular design that supports multiple output sinks, customizable formatting, and flexible filtering.

Features

• Multiple log levels
• ANSI color support
• Fully customizable output format
• Filters support
• Support for multiple sinks (stdout, file, etc.)
• c11/c99 compatible (with -pedantic file)

Table of Contents

• Quick Start
• Installation
• Basic Usage
• Log Levels
• Architecture Overview
  • Formatter
  • Writer
  • Filter
• Configuration Macros
• Recursive Logging
• Sinks and Output Configuration
  • Default sink
  • Creating a Custom Sink
• Module-Based Logging
• Memory Management Notes
• Format Tokens
  • Format Examples
• Filters
  • Custom Filter Function
• Limitations
• Usage in libraries
• License

Quick Start

#define LOGCIE_IMPLEMENTATION
#include "logcie.h"

int main() {
    LOGCIE_INFO("Application started");
    LOGCIE_DEBUG("Processing value: %d", 42);
    LOGCIE_WARN("This is a warning message");
    LOGCIE_ERROR("An error occurred: %s", "file not found");
    return 0;
}

Installation

Copy logcie.h into your project and include it.

// In one file (main.c, libs.c, etc)
#define LOGCIE_IMPLEMENTATION
#include "logcie.h"

// In any other file where you want to use logcie
#include "logcie.h"

Configuration Macros

Define any of these before you include logcie.h (or before #define LOGCIE_IMPLEMENTATION) to customise Logcie.

Macro	Description	Default
LOGCIE_MODULE	Module name attached to classic macros (LOGCIE_INFO, …). (see Module-Based Logging)	"Logcie"
LOGCIE_DEFAULT_SINK_FORMAT	Format string for the automatic stdout sink.	"$c$L$r … $f:$x$r: $m"
LOGCIE_THREAD_SAFE	Enables a mutex around all sink operations and log calls (requires pthreads).	(not defined)
LOGCIE_ALLOW_RECURSIVE_LOGGING	Allows logging calls inside formatters/writers/filters (dangerous!). (see Recursive Logging)	(not defined)
LOGCIE_DEF	Linkage qualifier for public functions (e.g. static).	extern
LOGCIE_PEDANTIC	Forces the strict C99 macro fallback (LOGCIE_*_VA) even on GCC/Clang.	(not defined)
LOGCIE_COLOR_*	ANSI escape codes for each level colour. You can override them or use logcie_set_colors().	(see source)

Note: The compiler‑pedantic fallback (LOGCIE_VA_LOGS) is automatically defined when variadic macros are not available – you don’t need to touch it.

Building examples and tests

On Linux you can compile the build system with:

cc -o build build.c

Then run it with:

./build --help

Basic Usage

Logcie provides macros for all log levels that automatically capture the file name and line number:

LOGCIE_TRACE("Detailed tracing information");
LOGCIE_DEBUG("Debug value: %d", some_value);
LOGCIE_VERBOSE("Additional verbose details");
LOGCIE_INFO("Informational message");
LOGCIE_WARN("Warning: %s", warning_message);
LOGCIE_ERROR("Error code: %d", error_code);
LOGCIE_FATAL("Fatal error, shutting down");

All macros support printf-style formatting. The message string supports the same format specifiers as printf().

Log Levels

Logcie defines seven log levels in increasing order of severity:

Level	Description	Typical Use
TRACE	Most detailed information	Function entry/exit, variable values
DEBUG	Debugging information	State changes, intermediate results
VERBOSE	Verbose operational details	Configuration loading, minor events
INFO	General information	Startup messages, major events
WARN	Warning conditions	Recoverable errors, deprecated usage
ERROR	Error conditions	Operation failures, unexpected states
FATAL	Fatal conditions	Unrecoverable errors, immediate shutdown

Architecture Overview

Logcie is built around three core components:

Formatter

Transforms a log structure into formatted output and passes it to Writer

Writer

Handles where formatted output goes (FILE*, network, etc.).

Filter

Decides whether a log should be emitted.

A combination of these three components is called a Sink

Recursive Logging

Recursive logging from formatters, writers or filters is not supported!

By default, Logcie suppresses recursive log attempts to avoid infinite recursion and deadlocks. Recursive calls return 0 and produce no output.

If you want to avoid the small overhead of the recursion check, or if you intentionally rely on recursive logging and you know what you are doing you can disable the recursion guard:

#define LOGCIE_ALLOW_RECURSIVE_LOGGING

Disabling the recursion guard may cause infinite recursion, deadlocks, or stack overflows.

Sinks and Output Configuration

A sink defines where log messages are written and how they are formatted. You can add additional sinks for files, network sockets, or custom destinations.

Default sink

Logcie provides a default stdout sink automatically, so you can start logging immediately.

This is how default sinks looks like:

static Logcie_Sink default_stdout_sink = {
    .formatter = {logcie_printf_formatter, "$c$L$r " LOGCIE_COLOR_GRAY "$f:$x$r: $m"},
    .writer    = {logcie_printf_writer, stdout},
    .filter    = {NULL, NULL},
};

However, when you add your first Sink using logcie_add_sink(), the default printf Sink is removed. This design choice ensures you have full control over sink configuration once you start customizing.

Important behaviors to understand:

• Initial state: By default, one stdout sink exists at index 0
• First sink addition: When you add your first custom sink, the default sink is removed
• Restoring defaults: Use logcie_remove_all_sinks() to return to the initial default configuration

If you want to keep both the default stdout sink and add additional sinks, you must re-add it explicitly.

Creating a Custom Sink

// Create a file sink for error logs
Logcie_Sink error_sink = {
    // nice format: date, time, level, module, message
    .formatter = {logcie_printf_formatter,  "$d $t [$L] $f:$x - $m"},
    .writer    = {logcie_printf_writer, fopen("errors.log", "a")},
    .filter    = {logcie_filter_level_min_fn, LOGCIE_LEVEL_ERROR}
};

// Add it to the logger
logcie_add_sink(&error_sink);

If you want to keep default sink you can do it like this:

Logcie_Sink *default_sink = logcie_get_sink(0);
logcie_add_sink(&file_sink);
logcie_add_sink(&default_sink);

Module-Based Logging

A module is a string label that identifies the origin of a log message, such as "network", "core", or "database". It can be displayed with the $M token and used in filters.

Logcie supports three ways to set the module, from simplest to most explicit:

Per‑file default (macro)

#define LOGCIE_MODULE "core"
#include "logcie.h"

All classic macros (LOGCIE_INFO, LOGCIE_ERROR, …) in that file will be tagged with "core".

Per‑call explicit module

LOGCIE_LOG_MOD("network", INFO, "Connected");
// Use LOGCIE_LOG_MOD_VA when variadic macros are unavailable.

Library integration

See the Usage in libraries section for a ready‑to‑use snippet.

The module name appears in logs when using the $M format token:

LOGCIE_LOG_MOD("network", INFO, "Connection established to %s", "gnu.org");
// With format "$d $t [$L] ($M) $m" produces:
// 2026-05-26 12:00:00 [INFO] (network) Connection established to gnu.org

Modules can also be used in filters to selectively allow or block logs from specific parts of your application.

Memory Management Notes

Since logcie_add_sink() stores the pointer to your sink structure (not a copy), you must ensure:

• Stack-allocated sinks: Must not go out of scope while registered
• Heap-allocated sinks: Must be freed only after removal
• Modification: You can modify sink properties after adding (changes take effect immediately)

Format Tokens

Format strings use $ tokens to insert log metadata. The default formatter supports the following tokens:

Token	Description	Example Output
$m	Log message with printf formatting	"Connection established"
$f	Source file name	"main.c"
$x	Line number	"42"
$M	Module name	"network"
$l	Log level (lowercase)	"info"
$L	Log level (uppercase)	"INFO"
$c	ANSI color code for log level	\x1b[36;20m
$r	ANSI reset color code	\x1b[0m
$d	Date (YYYY-MM-DD)	"2025-12-24"
$t	Time (HH:MM:SS)	"14:30:15"
$z	Timezone offset	"+3"
$<n	Pads with n spaces	" "
$$	Literal dollar sign	"$"

Format Examples

// Simple format with color
"$c$L$r: $m"

// Detailed format with timestamp and location
"$d $t [$L] $f:$x - $m"

// Module-based format
"[$M] $c$L$r $t - $m"

Filters

Filters allow you to control which logs are emitted to a specific Sink. Each Sink can have its own filter, enabling fine-grained routing of logs.

A filter is a structure that consist of pointer to filtering function and a pointer to custom data that filter might want to use.

A filtering function is simply a function that receives a Logcie_Log and returns:

• 1 (true) - to allow the log
• 0 (false) - to suppress the log

If a Sink has no filter all logs are allowed.

Here is a list of built-in filters:

• logcie_filter_level_min(level) Allows logs with level >= specified level

• logcie_filter_level_max(level) Allows logs with level <= specified level

• logcie_filter_module_eq("module") Allows logs only from specific module (see below for learning about modules)

• logcie_filter_message_contains("text") Allows logs whose messages contains the given substring

Combining filters:

• logcie_filter_and(a, b) - Allows logs only if BOTH filters pass
• logcie_filter_or(a, b) - Allows logs only if EITHER filters pass
• logcie_filter_not(a) - Inverts the result of a filter

Example:

// Sink that takes logs with level more than VERBOSE and not from "network" module
Logcie_Sink sink = {
  //...
  .filter = logcie_filter_and(
    logcie_filter_level_min(LOGCIE_VERBOSE),
    logcie_filter_not(
      logcie_filter_module_eq("network")
    )
  )
};

uint8_t custom_filter_fn(void *data, Logcie_Log *log) {
  (void) data; // ignored

  // Do not allow logs from even lines
  return log->location.line % 2 == 0;
}

Logcie_Sink another_sink = {
  // ...
  .filter = (Logcie_Filter) {
    .filter = custom_filter_fn,
    .data = NULL,
  }
}

// Or if you do not need any custom data and you want to
// deal with creating custom structs you can do this:

Logcie_Sink another_sink = {
  // ...
  .filter = {
    .filter = custom_filter_fn,
    .data = NULL,
  }
}

Notes:

• Filters are evaluated per sink, independently.
• Be careful when using temporary data in filters (they rely on compound literals and must remain valid during logging).

Limitations

• Thread safety is opt‑in – Define LOGCIE_THREAD_SAFE before the implementation to serialise all operations with a mutex. Without it, concurrent calls may interleave or crash.
• Memory allocation - The sink array uses malloc()/realloc() for dynamic growth
• No built-in log rotation - File management must be handled by the application (or just use logrotate)
• Custom formatters require va_list handling - Advanced usage requires understanding of variadic arguments

Future versions may address these limitations based on user feedback and requirements.

Usage in libraries

You can add simple snippet to make your library support logcie

// Logcie integration

#ifndef YOURLIB_LOG
  #ifdef LOGCIE
    #ifdef LOGCIE_VA_LOGS
      #define YOURLIB_LOG(level, msg, ...) LOGCIE_LOG_MOD_VA("YOURLIB", level, msg, __VA_ARGS__)
    #else
      #define YOURLIB_LOG(level, ...)      LOGCIE_LOG_MOD("YOURLIB", level, __VA_ARGS__)
    #endif
  #else
    #define YOURLIB_LOG(level, ...) (void*)0
  #endif
#endif

If you need to have fallback logging this can be used instead of (void *)0:

#define YOURLIB_LOG(level, ...)                \
   do {                                       \
     fprintf(stderr, #level ": "__VA_ARGS__); \
     fprintf(stderr, "\n");                   \
   } while (0)

Just change YOURLLIB to something more fitting :)

License

Logcie is released under the MIT License. See LICENSE file for more info

For questions or contributions, contact: Nikita (Strongleong) Chulkov nikita_chul@mail.ru