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

NAME

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

SYNOPSIS

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

DESCRIPTION

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

EXAMPLES

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

BUGS

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

SEE ALSO

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

AUTHOR

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