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