facil.io
Utilities & Parsers

#Signal Monitoring

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

A small wrapper around OS signals. It sets a handler, records that the signal fired, and lets you call the real callback later from normal execution context — the safe pattern, since signal handlers are heavily restricted. POSIX and Windows are supported.

#Configuration Macros

#FIO_SIGNAL_MONITOR_MAX

c
#ifndef FIO_SIGNAL_MONITOR_MAX
#define FIO_SIGNAL_MONITOR_MAX 24
#endif

Maximum number of signals that can be monitored at once.

#Portable Signal Aliases

#FIO_SIGNAL_USER1 / FIO_SIGNAL_USER2 / FIO_SIGNAL_USER_UNREGISTERED

c
#if FIO_OS_POSIX
#define FIO_SIGNAL_USER1             SIGUSR1
#define FIO_SIGNAL_USER2             SIGUSR2
#define FIO_SIGNAL_USER_UNREGISTERED SIGUSR2
#elif FIO_OS_WIN
#define FIO_SIGNAL_USER1             SIGBREAK
#define FIO_SIGNAL_USER2             SIGABRT
#define FIO_SIGNAL_USER_UNREGISTERED SIGBREAK
#endif

Maps user signals across POSIX and Windows.

#Types

#fio_signal_monitor_args_s

c
typedef struct {
  int sig;
  void (*callback)(int sig, void *udata);
  void *udata;
  bool propagate;
  bool immediate;
} fio_signal_monitor_args_s;
  • sig — signal number to watch.
  • callback — function to run; NULL ignores the signal.
  • udata — opaque pointer passed to the callback.
  • propagate — if true, call any previous handler after recording the signal.
  • immediate — if true, run the callback inside the signal handler; otherwise defer to fio_signal_review.

#API Functions

#fio_signal_monitor

c
SFUNC int fio_signal_monitor(fio_signal_monitor_args_s args);
#define fio_signal_monitor(...)                                                \
  fio_signal_monitor((fio_signal_monitor_args_s){__VA_ARGS__})

Starts monitoring sig. Updating an existing monitor replaces its callback and udata. Returns 0 on success, -1 on error.

Note: immediate callbacks must be async-signal-safe. Most code is not.

#fio_signal_review

c
SFUNC int fio_signal_review(void);

Calls deferred callbacks for any signals that fired since the last review. Returns the number of callbacks invoked.

#fio_signal_forget

c
SFUNC int fio_signal_forget(int sig);

Stops monitoring sig and restores the default handler. Returns 0 on success, -1 on error.

#Example

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

static volatile int running = 1;

static void on_sigint(int sig, void *udata) {
  (void)sig; (void)udata;
  FIO_LOG_INFO("SIGINT received, shutting down...");
  running = 0;
}

int main(void) {
  fio_signal_monitor(.sig = SIGINT,
                     .callback = on_sigint,
                     .udata = NULL);

  while (running) {
    fio_signal_review();
    /* do work */
  }

  fio_signal_forget(SIGINT);
  return 0;
}