1libtraceevent(3)
2================
3
4NAME
5----
6tep_list_events, tep_list_events_copy -
7Get list of events, sorted by given criteria.
8
9SYNOPSIS
10--------
11[verse]
12--
13*#include <event-parse.h>*
14
15enum *tep_event_sort_type* {
16	_TEP_EVENT_SORT_ID_,
17	_TEP_EVENT_SORT_NAME_,
18	_TEP_EVENT_SORT_SYSTEM_,
19};
20
21struct tep_event pass:[*]pass:[*]*tep_list_events*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
22struct tep_event pass:[*]pass:[*]*tep_list_events_copy*(struct tep_handle pass:[*]_tep_, enum tep_event_sort_type _sort_type_);
23--
24
25DESCRIPTION
26-----------
27The _tep_list_events()_ function returns an array of pointers to the events,
28sorted by the _sort_type_ criteria. The last element of the array is NULL.
29The returned memory must not be freed, it is managed by the library.
30The function is not thread safe. The _tep_ argument is trace event parser
31context. The _sort_type_ argument is the required sort criteria:
32[verse]
33--
34	_TEP_EVENT_SORT_ID_	- sort by the event ID.
35	_TEP_EVENT_SORT_NAME_	- sort by the event (name, system, id) triplet.
36	_TEP_EVENT_SORT_SYSTEM_	- sort by the event (system, name, id) triplet.
37--
38
39The _tep_list_events_copy()_ is a thread safe version of _tep_list_events()_.
40It has the same behavior, but the returned array is allocated internally and
41must be freed by the caller. Note that the content of the array must not be
42freed (see the EXAMPLE below).
43
44RETURN VALUE
45------------
46The _tep_list_events()_ function returns an array of pointers to events.
47In case of an error, NULL is returned. The returned array must not be freed,
48it is managed by the library.
49
50The _tep_list_events_copy()_ function returns an array of pointers to events.
51In case of an error, NULL is returned. The returned array must be freed by
52the caller.
53
54EXAMPLE
55-------
56[source,c]
57--
58#include <event-parse.h>
59...
60struct tep_handle *tep = tep_alloc();
61...
62int i;
63struct tep_event_format **events;
64
65i=0;
66events = tep_list_events(tep, TEP_EVENT_SORT_ID);
67if (events == NULL) {
68	/* Failed to get the events, sorted by ID */
69} else {
70	while(events[i]) {
71		/* walk through the list of the events, sorted by ID */
72		i++;
73	}
74}
75
76i=0;
77events = tep_list_events_copy(tep, TEP_EVENT_SORT_NAME);
78if (events == NULL) {
79	/* Failed to get the events, sorted by name */
80} else {
81	while(events[i]) {
82		/* walk through the list of the events, sorted by name */
83		i++;
84	}
85	free(events);
86}
87
88...
89--
90
91FILES
92-----
93[verse]
94--
95*event-parse.h*
96	Header file to include in order to have access to the library APIs.
97*-ltraceevent*
98	Linker switch to add when building a program that uses the library.
99--
100
101SEE ALSO
102--------
103_libtraceevent(3)_, _trace-cmd(1)_
104
105AUTHOR
106------
107[verse]
108--
109*Steven Rostedt* <rostedt@goodmis.org>, author of *libtraceevent*.
110*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>, author of this man page.
111--
112REPORTING BUGS
113--------------
114Report bugs to  <linux-trace-devel@vger.kernel.org>
115
116LICENSE
117-------
118libtraceevent is Free Software licensed under the GNU LGPL 2.1
119
120RESOURCES
121---------
122https://git.kernel.org/pub/scm/linux/kernel/git/torvalds/linux.git
123