1RECORDER(3) Recorder Library RECORDER(3)
4
8 RECORDER, RECORDER_DEFINE, RECORDER_DECLARE - Declare and define buf‐
9 fers to record events
10
14 #include <recorder/recorder.h>
15 #define RECORDER(recname, recsize, rechelp) ...
17 #define RECORDER_DEFINE(recname, recsize, rechelp) ...
18 #define RECORDER_DECLARE(recname) ...
19
21 The RECORDER() macro defines a buffer named recname to store up to rec‐
22 size events for use by the record(3) function. The rechelp string is
23 self-documentation describing the events stored in the buffer. This
24 self-documentation can be displayed by activating the help trace, see
25 recorder_set_trace(3).
26 The RECORDER_DECLARE() macro declares an event recorder, and can be
29 used in header files.
30 The RECORDER_DEFINE() macro is an alias for RECORDER(), the intention
33 being that you would use RECORDER() for event recorders that are local
34 to a file, or a RECORDER_DECLARE() (in the header file) paired with
35 RECORDER_DEFINE() (in a non-header file) for event recorders that are
36 shared across multiple translation units.
37 These macros should be used at file scope, i.e. where a function defi‐
40 nition or global variable is allowed.
41 Each recorder is associated with a trace value which is an integer
44 value that can be read using RECORDER_TRACE(3). See
45 recorder_trace_set(3).
46
50 The program below records its input arguments, and crashes if passed
51 crash as the first command-line argument.
52 #include <recorder/recorder.h>
54 #include <string.h>
55 RECORDER(program_args, 32, "Program command-line arguments");
57 int main(int argc, char **argv)
58 {
59 int a;
60 recorder_dump_on_common_signals(0, 0);
61 for (a = 0; a < argc; a++)
62 record(program_args, "Argument %d is %+s", a, argv[a]);
63 if (argc >= 2 && strcmp(argv[1], "crash") == 0)
65 {
66 char *ptr = NULL;
67 strcpy(ptr, argv[1]);
68 }
69 }
70 When a crash occurs, previously recorded events are printed out on the
72 console.
73 The program below is an instrumented version of the classical recursive
76 Fibonacci computation. It uses several recorders corresponding to dif‐
77 ferent types of events, and activates warnings and errors in a way that
78 can be configured by setting an environment variable.
79 #include <recorder/recorder.h>
81 #include <string.h>
82 #include <stdio.h>
83 #include <stdlib.h>
84 RECORDER(fib_main, 32, "Loops in fib function");
86 RECORDER(fib_loops, 32, "Loops in fib function");
87 RECORDER(fib_warning, 32, "Warnings in fib function");
88 RECORDER(fib_error, 32, "Errors in fib function");
89 int fib(int n)
91 {
92 if (n <= 1) {
93 if (n < 0)
94 record(fib_error, "fib is undefined for negative value %d", n);
95 return n;
96 }
97 record(fib_loops, "Computing fib(%d)", n);
98 int result = fib(n-1) + fib(n-2);
99 record(fib_loops, "Computed fib(%d) = %d", n, result);
100 return result;
101 }
102 int main(int argc, char **argv)
104 {
105 int a;
106 recorder_dump_on_common_signals(0, 0);
107 recorder_trace_set(".*_warning=35 .*_error");
108 recorder_trace_set(getenv("FIB_TRACES"));
109 for (a = 1; a < argc; a++) {
110 int n = atoi(argv[a]);
111 if (n >= RECORDER_TRACE(fib_warning))
112 record(fib_warning, "Computing for %d may take a while", n);
113 printf("fib(%d) = %d0, n, fib(n));
114 if (n >= RECORDER_TRACE(fib_warning))
115 record(fib_warning, "Computation for %d finally completed", n);
116 }
117 }
118 This program will produce an output similar to the following:
120 % fib 1 2 3 4 10 20 30 35 10 40 -1
122 fib(1) = 1
123 fib(2) = 1
124 fib(3) = 2
125 fib(4) = 3
126 fib(10) = 55
127 fib(20) = 6765
128 fib(30) = 832040
129 [2714667 0.177725] fib_warning: Computing for 35 may take a while
130 fib(35) = 9227465
131 [32575370 1.859156] fib_warning: Computation for 35 finally completed
132 fib(10) = 55
133 [32575547 1.859171] fib_warning: Computing for 40 may take a while
134 fib(40) = 102334155
135 [363735828 20.527882] fib_warning: Computation for 40 finally completed
136 [363735829 20.527887] fib_error: fib is undefined for negative value -1
137 fib(-1) = -1
138 The first column in trace outputs is the number of events that were
139 recorded. THe second column is the time in seconds since the program
140 started.
141 The same program can also be run with additional tracing or warnings,
144 for example:
145 % FIB_TRACES="recorder_location fib_loops fib_warning=3" /tmp/fib 3 4
147 /tmp/fib.c:33:[82 0.000496] fib_warning: Computing for 3 may take a while
148 /tmp/fib.c:18:[83 0.000561] fib_loops: Computing fib(3)
149 /tmp/fib.c:18:[84 0.000570] fib_loops: Computing fib(2)
150 /tmp/fib.c:20:[85 0.000575] fib_loops: Computed fib(2) = 1
151 /tmp/fib.c:20:[86 0.000581] fib_loops: Computed fib(3) = 2
152 fib(3) = 2
153 /tmp/fib.c:36:[87 0.000590] fib_warning: Computation for 3 finally completed
154 /tmp/fib.c:33:[88 0.000596] fib_warning: Computing for 4 may take a while
155 /tmp/fib.c:18:[89 0.000601] fib_loops: Computing fib(4)
156 /tmp/fib.c:18:[90 0.000607] fib_loops: Computing fib(3)
157 /tmp/fib.c:18:[91 0.000612] fib_loops: Computing fib(2)
158 /tmp/fib.c:20:[92 0.000619] fib_loops: Computed fib(2) = 1
159 /tmp/fib.c:20:[93 0.000625] fib_loops: Computed fib(3) = 2
160 /tmp/fib.c:18:[94 0.000664] fib_loops: Computing fib(2)
161 /tmp/fib.c:20:[95 0.000707] fib_loops: Computed fib(2) = 1
162 /tmp/fib.c:20:[96 0.000724] fib_loops: Computed fib(4) = 3
163 fib(4) = 3
164 /tmp/fib.c:36:[97 0.000741] fib_warning: Computation for 4 finally completed
165
169 Incorrect use of the macros generally results in nonsensical compiler
170 diagnostics.
171 Bugs should be reported using https://github.com/c3d/recorder/issues.
174
178 record(3), record_fast(3)
179 recorder_trace_set(3) RECORDER_TRACE(3)
180 recorder_dump(3), recorder_dump_for(3),
181 recorder_configure_output(3), recorder_configure_show(3)
182 recorder_configure_format(3), recorder_configure_type(3)
183 Additional documentation and tutorials can be found at
186 https://github.com/c3d/recorder.
187
191 Written by Christophe de Dinechin
1921.0 2019-03-09 RECORDER(3)