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
|
libtracefs(3)
=============
NAME
----
tracefs_tracers, tracefs_tracer_available, tracefs_get_clock, tracefs_list_free,
tracefs_list_add, tracefs_list_size - Helper functions for working with trace file system.
SYNOPSIS
--------
[verse]
--
*#include <tracefs.h>*
char pass:[*]pass:[*]*tracefs_tracers*(const char pass:[*]_tracing_dir_);
bool *tracefs_tracer_available*(const char pass:[*]_tracing_dir_, const char pass:[*]_tracer_);
char pass:[*]*tracefs_get_clock*(struct tracefs_instance pass:[*]_instance_);
void *tracefs_list_free*(char pass:[*]pass:[*]_list_);
char pass:[**]*tracefs_list_add*(char **_list_, const char *_string_);
int *tracefs_list_size*(char pass:[**]_list_);
--
DESCRIPTION
-----------
Various useful functions for working with trace file system.
The *tracefs_tracers()* function returns array of strings with the
names of supported tracer plugins, located in the given _tracing_dir_
directory. This could be NULL or the location of the tracefs mount point
for the trace systems of the local machine, or it may be a path to a copy
of the tracefs directory from another machine. The last entry in the array
as a NULL pointer. The array must be freed with *tracefs_list_free()* API.
The *tracefs_tracer_available()* returns true if the _tracer_ is available
in the given _tracing_dir_director_, and false otherwise.
The *tracefs_get_clock()* function returns name of the current trace clock,
used in the given _instance_. If _instance_ is NULL, the clock of the main
trace instance is returned. The returned string must be freed with free().
The *tracefs_list_free()* function frees an array of strings, returned by
*tracefs_event_systems()*, *tracefs_system_events()* and *tracefs_tracers()*
APIs.
The *tracefs_list_add()* function adds _string_ to the string _list_. If
_list_ is NULL, then a new list is created with the first element a copy
of _string_, and the second element will be a NULL pointer. If _list_ is
not NULL, then it is reallocated to include a new element and a NULL terminator,
and the new allocated array is returned. The list passed in should be ignored,
as it wil be freed if a new one was allocated.
The *tracefs_list_size()* is a fast way to find out the number of elements
in a string array that is to be freed with *tracefs_list_free()*. Note, this
depends on meta data that is created for these lists and will not work on
normal string arrays like argv.
RETURN VALUE
------------
The *tracefs_tracers()* returns array of strings. The last element in that
array is a NULL pointer. The array must be freed with *tracefs_list_free()* API.
In case of an error, NULL is returned.
The *tracefs_tracer_available()* returns true if the _tracer_ is available,
and false otherwise.
The *tracefs_get_clock()* returns string, that must be freed with free(), or NULL
in case of an error.
The *tracefs_list_add()* returns an allocated string array that must be freed
with *tracefs_list_free()* on success or NULL on error. If NULL is returned,
then the passed in _list_ is untouched. Thus, *tracefs_list_add()* should be
treated similarly to *realloc*(3).
The *tracefs_list_size()* returns the number of strings in the _list_. The
passed in list must be one that is to be freed with *tracefs_list_free()*
as the list has meta data that is used to determine the size and this does
not work on any normal string array like argv.
EXAMPLE
-------
[source,c]
--
#include <tracefs.h>
char **tracers = tracefs_tracers(NULL);
if (tracers) {
/* Got tracer plugins from the top trace instance */
...
tracefs_list_free(tracers);
}
....
char *clock = tracefs_get_clock(NULL);
if (clock) {
/* Got current trace clock of the top trace instance */
...
free(clock);
}
--
FILES
-----
[verse]
--
*tracefs.h*
Header file to include in order to have access to the library APIs.
*-ltracefs*
Linker switch to add when building a program that uses the library.
--
SEE ALSO
--------
*libtracefs*(3),
*libtraceevent*(3),
*trace-cmd*(1)
AUTHOR
------
[verse]
--
*Steven Rostedt* <rostedt@goodmis.org>
*Tzvetomir Stoyanov* <tz.stoyanov@gmail.com>
--
REPORTING BUGS
--------------
Report bugs to <linux-trace-devel@vger.kernel.org>
LICENSE
-------
libtracefs is Free Software licensed under the GNU LGPL 2.1
RESOURCES
---------
https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
COPYING
-------
Copyright \(C) 2020 VMware, Inc. Free use of this software is granted under
the terms of the GNU Public License (GPL).
|
