record(3)

📦 version 1.2.3, in fedora 43, fedora 44

💖 record(3) — the Recorder Library, bestie edition 💖

okay so you found the record page in the Recorder Library and honestly? slay. this is the function that quietly logs everything your program does so that when it inevitably faceplants, you actually have receipts. no cap.

✨ NAME ✨

record, record_fast — fast event logging in circular buffers 🌀

🌸 SYNOPSIS 🌸

#include <recorder/recorder.h>

ringidx_t record(recorder_name recname, const char *format, ...);
ringidx_t record_fast(recorder_name recname, const char *format, ...);

🦋 DESCRIPTION 🦋

record() stores an event in the recorder identified by recname. bestie, that event record is packing a time stamp from gettimeofday(3) (or some similar absolute-time function), plus the format string, plus up to 12 additional arguments. the format string follows printf(3) conventions, with the exceptions and additions spelled out below. periodt.

record_fast() is the lowkey efficient sibling — it reuses the time stamp of the previous record() call for the same recorder, which makes it approximately twice as fast on some modern systems. the cost difference should be on the order of the cost of a call like gettimeofday(3). 💅

event recording code is designed to stay active in your program at all times. unlike your typical printf(3) messages, events recorded by record() are not generally meant to be seen immediately — they're meant to be shown laster, like, for example in case of a crash. see recorder_dump(3). the formatting only actually happens when the message is really printed. so it's giving "I'll deal with it later" and honestly, valid. 😌

events can also be traced on a per-recorder basis. in that case, record() and record_fast() will immediately format their output. see recorder_set_trace(3).

🎀 Automatic end of line 🎀

event records are always printed on an individual line, bestie. you do not need to add a \n at the end of the format string. if one is present, it will have no effect. iconic.

record(my_recorder, "Hello");
record(my_recorder, "World0);

using \n at other positions in the string is possible and has the usual effect. 💫

🍓 Formatting character strings: %s and %+s 🍓

since formatting an event may happen at some unknown time after it was recorded, the %s and S formats get treated like %p — unless formatting happens as part of tracing. so if you're passing a character string that's known to be constant, or at least still valid at the moment it gets formatted, then bestie you can use the %+s format instead. 🫶

const char *name[2] = { "false", "true" };
record(my_recorder, "Value %d is %+s", value, name[!!value]);

🌈 Extended format characters 🌈

you can configure additional format characters. see recorder_configure_type. when this function gets used, format strings may deviate notably from the printf(3) standard, or may conflict with other extensions to that standard. so like… heads up. ⚠️

💫 RETURN VALUE 💫

the return value is the index of the event that was recorded. this value is rarely useful and can generally be ignored. it's giving decorative. 🙈

👑 EXAMPLES 👑

the program below records its input arguments, and crashes if you pass crash as the first command-line argument. dramatic? yes. educational? also yes.

#include <recorder/recorder.h>
#include <string.h>

RECORDER(program_args, 32, "Program command-line arguments");
int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    for (a = 0; a < argc; a++)
        record(program_args, "Argument %d is %+s", a, argv[a]);

    if (argc >= 2 && strcmp(argv[1], "crash") == 0)
    {
        char *ptr = NULL;
        strcpy(ptr, argv[1]);
    }
}

when a crash occurs, the previously recorded events are printed out on the console. see? the receipts came through. 💀

the program below is an instrumented version of the classical recursive Fibonacci computation. it uses several recorders corresponding to different types of events, and activates warnings and errors in a way that can be configured by setting an environment variable. main character energy fr fr. ✨

#include <recorder/recorder.h>
#include <string.h>
#include <stdio.h>
#include <stdlib.h>

RECORDER(fib_main,    32, "Loops in fib function");
RECORDER(fib_loops,   32, "Loops in fib function");
RECORDER(fib_warning, 32, "Warnings in fib function");
RECORDER(fib_error,   32, "Errors in fib function");

int fib(int n)
{
    if (n <= 1) {
        if (n < 0)
            record(fib_error, "fib is undefined for negative value %d", n);
        return n;
    }
    record(fib_loops, "Computing fib(%d)", n);
    int result = fib(n-1) + fib(n-2);
    record(fib_loops, "Computed fib(%d) = %d", n, result);
    return result;
}

int main(int argc, char **argv)
{
    int a;
    recorder_dump_on_common_signals(0, 0);
    recorder_trace_set(".*_warning=35 .*_error");
    recorder_trace_set(getenv("FIB_TRACES"));
    for (a = 1; a < argc; a++) {
        int n = atoi(argv[a]);
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computing for %d may take a while", n);
        printf("fib(%d) = %d0, n, fib(n));
        if (n >= RECORDER_TRACE(fib_warning))
            record(fib_warning, "Computation for %d finally completed", n);
    }
}

this program will produce an output similar to the following:

% fib 1 2 3 4 10 20 30 35 10 40 -1
fib(1) = 1
fib(2) = 1
fib(3) = 2
fib(4) = 3
fib(10) = 55
fib(20) = 6765
fib(30) = 832040
[2714667 0.177725] fib_warning: Computing for 35 may take a while
fib(35) = 9227465
[32575370 1.859156] fib_warning: Computation for 35 finally completed
fib(10) = 55
[32575547 1.859171] fib_warning: Computing for 40 may take a while
fib(40) = 102334155
[363735828 20.527882] fib_warning: Computation for 40 finally completed
[363735829 20.527887] fib_error: fib is undefined for negative value -1
fib(-1) = -1

the first column in trace outputs is the number of events that were recorded. THe second column is the time in seconds since the program started. ⏱️

the same program can also be run with additional tracing or warnings, for example:

% FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
/tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
/tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
/tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
/tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
fib(3) = 2
/tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
/tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
/tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
/tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
/tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
/tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
/tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
/tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
/tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
fib(4) = 3
/tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed

💀 BUGS 💀

there is a limit to the number of arguments that can be passed to record() and record_fast(). as of version 1.0, the maximum number is 12. if that number is exceeded, the compilation error message is not friendly. like, at all. it's giving unhelpful. 😭

bugs should be reported using https://github.com/c3d/recorder/issues.

🧚 SEE ALSO 🧚

additional documentation and tutorials can be found at https://github.com/c3d/recorder. 🌐

⭐ AUTHOR ⭐

written by Christophe de Dinechin. king behaviour, honestly. 👑

and that's the whole page bestie 💖 — this was Recorder Library version 1.0, dated 2019-03-09, and yes, the page is literally called record(3). go log some events, you got this. 🎀✨🦋

📦 where this page comes from