1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
|
libtraceevent(3)
================
NAME
----
tep_register_event_handler, tep_unregister_event_handler - Register /
unregisters a callback function to parse an event information.
SYNOPSIS
--------
[verse]
--
*#include <event-parse.h>*
enum *tep_reg_handler* {
_TEP_REGISTER_SUCCESS_,
_TEP_REGISTER_SUCCESS_OVERWRITE_,
};
int *tep_register_event_handler*(struct tep_handle pass:[*]_tep_, int _id_, const char pass:[*]_sys_name_, const char pass:[*]_event_name_, tep_event_handler_func _func_, void pass:[*]_context_);
int *tep_unregister_event_handler*(struct tep_handle pass:[*]tep, int id, const char pass:[*]sys_name, const char pass:[*]event_name, tep_event_handler_func func, void pass:[*]_context_);
typedef int (*pass:[*]tep_event_handler_func*)(struct trace_seq pass:[*]s, struct tep_record pass:[*]record, struct tep_event pass:[*]event, void pass:[*]context);
--
DESCRIPTION
-----------
The *tep_register_event_handler()* function registers a handler function,
which is going to be called to parse the information for a given event.
The _tep_ argument is the trace event parser context. The _id_ argument is
the id of the event. The _sys_name_ argument is the name of the system,
the event belongs to. The _event_name_ argument is the name of the event.
If _id_ is >= 0, it is used to find the event, otherwise _sys_name_ and
_event_name_ are used. The _func_ is a pointer to the function, which is going
to be called to parse the event information. The _context_ argument is a pointer
to the context data, which will be passed to the _func_. If a handler function
for the same event is already registered, it will be overridden with the new
one. This mechanism allows a developer to override the parsing of a given event.
If for some reason the default print format is not sufficient, the developer
can register a function for an event to be used to parse the data instead.
The *tep_unregister_event_handler()* function unregisters the handler function,
previously registered with *tep_register_event_handler()*. The _tep_ argument
is the trace event parser context. The _id_, _sys_name_, _event_name_, _func_,
and _context_ are the same arguments, as when the callback function _func_ was
registered.
The _tep_event_handler_func_ is the type of the custom event handler
function. The _s_ argument is the trace sequence, it can be used to create a
custom string, describing the event. A _record_ to get the event from is passed
as input parameter and also the _event_ - the handle to the record's event. The
_context_ is custom context, set when the custom event handler is registered.
RETURN VALUE
------------
The *tep_register_event_handler()* function returns _TEP_REGISTER_SUCCESS_
if the new handler is registered successfully or
_TEP_REGISTER_SUCCESS_OVERWRITE_ if an existing handler is overwritten.
If there is not enough memory to complete the registration,
TEP_ERRNO__MEM_ALLOC_FAILED is returned.
The *tep_unregister_event_handler()* function returns 0 if _func_ was removed
successful or, -1 if the event was not found.
The _tep_event_handler_func_ should return -1 in case of an error,
or 0 otherwise.
EXAMPLE
-------
[source,c]
--
#include <event-parse.h>
#include <trace-seq.h>
...
struct tep_handle *tep = tep_alloc();
...
int timer_expire_handler(struct trace_seq *s, struct tep_record *record,
struct tep_event *event, void *context)
{
trace_seq_printf(s, "hrtimer=");
if (tep_print_num_field(s, "0x%llx", event, "timer", record, 0) == -1)
tep_print_num_field(s, "0x%llx", event, "hrtimer", record, 1);
trace_seq_printf(s, " now=");
tep_print_num_field(s, "%llu", event, "now", record, 1);
tep_print_func_field(s, " function=%s", event, "function", record, 0);
return 0;
}
...
int ret;
ret = tep_register_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
timer_expire_handler, NULL);
if (ret < 0) {
char buf[32];
tep_strerror(tep, ret, buf, 32)
printf("Failed to register handler for hrtimer_expire_entry: %s\n", buf);
} else {
switch (ret) {
case TEP_REGISTER_SUCCESS:
printf ("Registered handler for hrtimer_expire_entry\n");
break;
case TEP_REGISTER_SUCCESS_OVERWRITE:
printf ("Overwrote handler for hrtimer_expire_entry\n");
break;
}
}
...
ret = tep_unregister_event_handler(tep, -1, "timer", "hrtimer_expire_entry",
timer_expire_handler, NULL);
if ( ret )
printf ("Failed to unregister handler for hrtimer_expire_entry\n");
--
FILES
-----
[verse]
--
*event-parse.h*
Header file to include in order to have access to the library APIs.
*trace-seq.h*
Header file to include in order to have access to trace sequences
related APIs. Trace sequences are used to allow a function to call
several other functions to create a string of data to use.
*-ltraceevent*
Linker switch to add when building a program that uses the library.
--
SEE ALSO
--------
*libtraceevent*(3), *trace-cmd*(1)
AUTHOR
------
[verse]
--
*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
--
REPORTING BUGS
--------------
Report bugs to <linux-trace-devel@vger.kernel.org>
LICENSE
-------
libtraceevent is Free Software licensed under the GNU LGPL 2.1
RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtraceevent.git/
|
