1
2
3RECORDER(3)                    Recorder Library                    RECORDER(3)
4
5
6

NAME

8       RECORDER,  RECORDER_DEFINE,  RECORDER_DECLARE - Declare and define buf‐
9       fers to record events
10
11
12

SYNOPSIS

14       #include <recorder/recorder.h>
15
16       #define RECORDER(recname, recsize, rechelp) ...
17       #define RECORDER_DEFINE(recname, recsize, rechelp) ...
18       #define RECORDER_DECLARE(recname) ...
19

DESCRIPTION

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
27
28       The RECORDER_DECLARE() macro declares an event  recorder,  and  can  be
29       used in header files.
30
31
32       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
38
39       These  macros should be used at file scope, i.e. where a function defi‐
40       nition or global variable is allowed.
41
42
43       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
47
48

EXAMPLES

50       The program below records its input arguments, and  crashes  if  passed
51       crash as the first command-line argument.
52
53           #include <recorder/recorder.h>
54           #include <string.h>
55
56           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
64               if (argc >= 2 && strcmp(argv[1], "crash") == 0)
65               {
66                   char *ptr = NULL;
67                   strcpy(ptr, argv[1]);
68               }
69           }
70
71       When  a crash occurs, previously recorded events are printed out on the
72       console.
73
74
75       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
80           #include <recorder/recorder.h>
81           #include <string.h>
82           #include <stdio.h>
83           #include <stdlib.h>
84
85           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
90           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
103           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
119       This program will produce an output similar to the following:
120
121           % 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
142
143       The  same  program can also be run with additional tracing or warnings,
144       for example:
145
146           % 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
166
167

BUGS

169       Incorrect use of the macros generally results in  nonsensical  compiler
170       diagnostics.
171
172
173       Bugs should be reported using https://github.com/c3d/recorder/issues.
174
175
176

SEE ALSO

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
184
185       Additional    documentation    and    tutorials   can   be   found   at
186       https://github.com/c3d/recorder.
187
188
189

AUTHOR

191       Written by Christophe de Dinechin
192
193
194
1951.0                               2019-03-09                       RECORDER(3)
Impressum