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
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
|
libtracefs(3)
=============
NAME
----
tracefs_instance_file_open,
tracefs_instance_file_write, tracefs_instance_file_append, tracefs_instance_file_clear,
tracefs_instance_file_read, tracefs_instance_file_read_number - Work with files in tracing instances.
SYNOPSIS
--------
[verse]
--
*#include <tracefs.h>*
int *tracefs_instance_file_open*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int _mode_);
int *tracefs_instance_file_write*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
int *tracefs_instance_file_append*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, const char pass:[*]_str_);
int *tracefs_instance_file_clear*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_);
char pass:[*]*tracefs_instance_file_read*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, int pass:[*]_psize_);
int *tracefs_instance_file_read_number*(struct tracefs_instance pass:[*]_instance_, const char pass:[*]_file_, long long int pass:[*]_res_);
--
DESCRIPTION
-----------
This set of APIs can be used to work with trace files in all trace instances.
Each of these APIs take an _instance_ argument, that can be NULL to act
on the top level instance. Otherwise, it acts on an instance created with
*tracefs_insance_create*(3)
The *tracefs_instance_file_open()* function opens trace _file_ from given _instance_ and returns
a file descriptor to it. The file access _mode_ can be specified, see *open*(3) for more details.
If -1 is passed as _mode_, default O_RDWR is used.
The *tracefs_instance_file_write()* function writes a string _str_ in a _file_ from
the given _instance_, without the terminating NULL character. When opening the file, this function
tries to truncates the size of the file to zero, which clears all previously existing settings.
The *tracefs_instance_file_append()* function writes a string _str_ in a _file_ from
the given _instance_, without the terminating NULL character. This function is similar to
*tracefs_instance_file_write()*, but the existing content of the is not cleared. Thus the
new settings are appended to the existing ones (if any).
The *tracefs_instance_file_clear()* function tries to truncates the size of the file to zero,
which clears all previously existing settings. If the file has content that does not get
cleared in this way, this will not have any effect.
The *tracefs_instance_file_read()* function reads the content of a _file_ from
the given _instance_.
The *tracefs_instance_file_read_number()* function reads the content of a _file_ from
the given _instance_ and converts it to a long long integer, which is stored in _res_.
RETURN VALUE
------------
The *tracefs_instance_file_open()* function returns a file descriptor to the opened file. It must be
closed with *close*(3). In case of an error, -1 is returned.
The *tracefs_instance_file_write()* function returns the number of written bytes,
or -1 in case of an error.
The *tracefs_instance_file_append()* function returns the number of written bytes,
or -1 in case of an error.
The *tracefs_instance_file_clear()* function returns 0 on success, or -1 in case of an error.
The *tracefs_instance_file_read()* function returns a pointer to a NULL terminated
string, read from the file, or NULL in case of an error. The returned string must
be freed with free().
The *tracefs_instance_file_read_number()* function returns 0 if a valid integer is read from
the file and stored in _res_ or -1 in case of an error.
EXAMPLE
-------
[source,c]
--
#include <tracefs.h>
struct tracefs_instance *inst = tracefs_instance_create("foo");
if (!inst) {
/* Error creating a new trace instance */
...
}
if (tracefs_file_exists(inst,"trace_clock")) {
/* The instance foo supports trace clock */
char *path, *clock;
int size;
path = = tracefs_instance_get_file(inst, "trace_clock")
if (!path) {
/* Error getting the path to trace_clock file in instance foo */
...
}
...
tracefs_put_tracing_file(path);
clock = tracefs_instance_file_read(inst, "trace_clock", &size);
if (!clock) {
/* Failed to read trace_clock file in instance foo */
...
}
...
free(clock);
if (tracefs_instance_file_write(inst, "trace_clock", "global") != strlen("global")) {
/* Failed to set gloabl trace clock in instance foo */
...
}
} else {
/* The instance foo does not support trace clock */
}
if (tracefs_dir_exists(inst,"options")) {
/* The instance foo supports trace options */
char *path = tracefs_instance_get_file(inst, "options");
if (!path) {
/* Error getting the path to options directory in instance foo */
...
}
tracefs_put_tracing_file(path);
} else {
/* The instance foo does not support trace options */
}
...
if (tracefs_instance_is_new(inst))
tracefs_instance_destroy(inst);
else
tracefs_instance_free(inst);
...
long long int res;
if (tracefs_instance_file_read_number(NULL, "tracing_on", &res) == 0) {
if (res == 0) {
/* tracing is disabled in the top instance */
} else if (res == 1) {
/* tracing is enabled in the top instance */
} else {
/* Unknown tracing state of the top instance */
}
} else {
/* Failed to read integer from tracing_on file */
}
...
int fd;
fd = tracefs_instance_file_open(NULL, "tracing_on", O_WRONLY);
if (fd >= 0) {
/* Got file descriptor to the tracing_on file from the top instance for writing */
...
close(fd);
}
--
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).
|
