facil.io
Core Library

#Logging and Assertions

c
#define FIO_LOG
#include "fio-stl.h"

Heap-allocation-free logging macros and assertion utilities. FIO_LOG2STDERR and the FIO_LOG_* macros are functional when FIO_LOG or FIO_LEAK_COUNTER is defined; otherwise they are no-ops.

FIO_LOG uses libc functions (vsnprintf, fwrite) and the library helper fio_memcpy32. If you are building without libc, provide your own implementations or shadowing macros before including the module.

#Log Levels

c
#define FIO_LOG_LEVEL_NONE    0  /* no logging */
#define FIO_LOG_LEVEL_FATAL   1  /* fatal errors */
#define FIO_LOG_LEVEL_ERROR   2  /* errors and above */
#define FIO_LOG_LEVEL_WARNING 3  /* warnings and above */
#define FIO_LOG_LEVEL_INFO    4  /* info and above */
#define FIO_LOG_LEVEL_DEBUG   5  /* everything, including debug */

#Log Level Control

#FIO_LOG_LEVEL_SET

c
#define FIO_LOG_LEVEL_SET(new_level) fio___log_level_set(new_level)

Sets the application-wide logging level. Returns the new level.

#FIO_LOG_LEVEL_GET

c
#define FIO_LOG_LEVEL_GET() ((fio___log_level()))

Returns the current logging level as an integer.

c
FIO_LOG_LEVEL_SET(FIO_LOG_LEVEL_WARNING);
int level = FIO_LOG_LEVEL_GET(); /* 3 */

#Configuration

#FIO_LOG_LEVEL_DEFAULT

Initial level. Defaults to FIO_LOG_LEVEL_INFO unless DEBUG is defined and truthy (defined(DEBUG) && DEBUG), in which case it is FIO_LOG_LEVEL_DEBUG.

#FIO_STDERR_FILE

c
#define FIO_STDERR_FILE stderr

Output destination for all logging. Define it before including ./fio-stl.h to redirect logs to another FILE*.

#FIO_LOG_LENGTH_LIMIT

c
#define FIO_LOG_LENGTH_LIMIT 1024

Log buffer size. Keep this above 128.

  • When FIO_LOG_LENGTH_LIMIT > 128, the formatted message is limited to FIO_LOG_LENGTH_LIMIT - 34 bytes, followed by a 32-byte truncation warning.
  • When FIO_LOG_LENGTH_LIMIT <= 128, vsnprintf is capped at FIO_LOG_LENGTH_LIMIT - 2 bytes; the truncation warning is appended afterward.
  • Values <= 2 are dangerous: the vsnprintf size argument underflows/overflows.

#Core Logging Function

#FIO_LOG2STDERR

c
void FIO_LOG2STDERR(const char *format, ...);

printf-style output to FIO_STDERR_FILE using only stack-allocated memory. Truncation follows the two FIO_LOG_LENGTH_LIMIT paths described above. In ./fio-stl/001 logging.h the name is #undef-ed before the static function definition, so a pre-include macro is removed and a post-inclusion function definition would conflict. Override it after inclusion only by defining FIO_LOG2STDERR as a macro.

#Log Macros

Most macros check the current log level before printing. FIO_LOG_WRITE has no level check and always prefixes output with the file and line number.

Macro Level Prefix
FIO_LOG_FATAL(...) ≥ FATAL FATAL: (bold inverse)
FIO_LOG_ERROR(...) ≥ ERROR ERROR: (bold)
FIO_LOG_SECURITY(...) ≥ ERROR SECURITY: (bold)
FIO_LOG_WARNING(...) ≥ WARNING WARNING: (dim)
FIO_LOG_INFO(...) ≥ INFO INFO:
FIO_LOG_DEBUG(...) ≥ DEBUG DEBUG: + file:line
FIO_LOG_DEBUG2(...) ≥ DEBUG DEBUG:
FIO_LOG_WRITE(...) always file:line

#Debug-Only Log Macros

These expand to their non-D counterparts when DEBUG is defined, and to no-ops otherwise.

  • FIO_LOG_DDEBUG(...)
  • FIO_LOG_DDEBUG2(...)
  • FIO_LOG_DERROR(...)
  • FIO_LOG_DSECURITY(...)
  • FIO_LOG_DWARNING(...)
  • FIO_LOG_DINFO(...)

#Assertions

#FIO_ASSERT

c
#define FIO_ASSERT(cond, ...)

If cond is false, prints a fatal message, prints errno and its string, sends SIGINT in debug builds, and calls exit(-1).

#FIO_ASSERT_ALLOC

c
#define FIO_ASSERT_ALLOC(ptr) FIO_ASSERT((ptr), "memory allocation failed.")

Convenience wrapper for allocation failures.

#FIO_ASSERT_DEBUG

c
#define FIO_ASSERT_DEBUG(cond, ...)

Active only when DEBUG is defined. On failure it behaves like FIO_ASSERT, printing the file and line number before terminating.

#FIO_ASSERT_STATIC

c
#define FIO_ASSERT_STATIC(cond, msg)

Compile-time assertion. cond must be a constant expression; msg is a string literal with no format specifiers. Falls back to a sized-array trick on pre-C11 compilers.

See also: [Compiler Attributes](./001 compiler attributes.md).

#Leak Counter Helpers

Enabled by FIO_LEAK_COUNTER (default 1). FIO_NO_LOG and FIO_LEAK_COUNTER are mutually exclusive because leak reports are printed through the log.

#FIO_LEAK_COUNTER_DEF

c
#define FIO_LEAK_COUNTER_DEF(name)

Defines a named counter and a cleanup function that reports remaining allocations at process exit.

#FIO_LEAK_COUNTER_ON_ALLOC

c
#define FIO_LEAK_COUNTER_ON_ALLOC(name)

Increment the named counter. Call after a successful allocation.

#FIO_LEAK_COUNTER_ON_FREE

c
#define FIO_LEAK_COUNTER_ON_FREE(name)

Decrement the named counter. Call when memory is freed. Detects double-free.

#FIO_LEAK_COUNTER_COUNT

c
#define FIO_LEAK_COUNTER_COUNT(name)

Returns the current value of the named counter.

#FIO_LEAK_COUNTER_SKIP_EXIT

c
#define FIO_LEAK_COUNTER_SKIP_EXIT 0

Set to 1 to prevent automatic leak reporting at exit.

#Example

c
#define FIO_LOG
#include "fio-stl.h"

int main(void) {
  FIO_LOG_LEVEL_SET(FIO_LOG_LEVEL_WARNING);

  FIO_LOG_INFO("not printed");
  FIO_LOG_WARNING("number invalid: %d", 42);

  FIO_LOG2STDERR("direct message");

  void *ptr = malloc(100);
  FIO_ASSERT_ALLOC(ptr);
  FIO_ASSERT(ptr != NULL, "expected a pointer");

  free(ptr);
  return 0;
}