xref: /aosp_15_r20/external/libtracefs/Documentation/libtracefs-eprobes.txt (revision 287e80b3a36113050663245e7f2c00d274188f18)
1*287e80b3SSadaf Ebrahimilibtracefs(3)
2*287e80b3SSadaf Ebrahimi=============
3*287e80b3SSadaf Ebrahimi
4*287e80b3SSadaf EbrahimiNAME
5*287e80b3SSadaf Ebrahimi----
6*287e80b3SSadaf Ebrahimitracefs_eprobe_alloc - Allocate new event probe (eprobe)
7*287e80b3SSadaf Ebrahimi
8*287e80b3SSadaf EbrahimiSYNOPSIS
9*287e80b3SSadaf Ebrahimi--------
10*287e80b3SSadaf Ebrahimi[verse]
11*287e80b3SSadaf Ebrahimi--
12*287e80b3SSadaf Ebrahimi*#include <tracefs.h>*
13*287e80b3SSadaf Ebrahimi
14*287e80b3SSadaf Ebrahimistruct tracefs_dynevent pass:[*]
15*287e80b3SSadaf Ebrahimi*tracefs_eprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_,
16*287e80b3SSadaf Ebrahimi		       const char pass:[*]_target_system_, const char pass:[*]_target_event_,
17*287e80b3SSadaf Ebrahimi		       const char pass:[*]_fetchargs_);
18*287e80b3SSadaf Ebrahimi--
19*287e80b3SSadaf Ebrahimi
20*287e80b3SSadaf EbrahimiDESCRIPTION
21*287e80b3SSadaf Ebrahimi-----------
22*287e80b3SSadaf Ebrahimi*tracefs_eprobe_alloc*() allocates a new eprobe context. The ebrobe is not configured in the system.
23*287e80b3SSadaf EbrahimiThe new eprobe will be in the _system_ group (or eprobes if _system_ is NULL) and have the name of
24*287e80b3SSadaf Ebrahimi_event_. The eprobe will be attached to _target_event_, located in _target_system_. The list of
25*287e80b3SSadaf Ebrahimiarguments, described in _fetchargs_, will be fetched from _target_event_. The returned pointer to
26*287e80b3SSadaf Ebrahimithe event probe must be freed with *tracefs_dynevent_free*().
27*287e80b3SSadaf Ebrahimi
28*287e80b3SSadaf Ebrahimi
29*287e80b3SSadaf EbrahimiRETURN VALUE
30*287e80b3SSadaf Ebrahimi------------
31*287e80b3SSadaf EbrahimiThe *tracefs_eprobe_alloc*() API returns a pointer to an allocated tracefs_dynevent structure,
32*287e80b3SSadaf Ebrahimidescribing the event probe. This pointer must be freed by *tracefs_dynevent_free*(3). Note, this
33*287e80b3SSadaf Ebrahimionly allocates a descriptor representing the eprobe. It does not modify the running system. On error
34*287e80b3SSadaf EbrahimiNULL is returned.
35*287e80b3SSadaf Ebrahimi
36*287e80b3SSadaf EbrahimiEXAMPLE
37*287e80b3SSadaf Ebrahimi-------
38*287e80b3SSadaf Ebrahimi[source,c]
39*287e80b3SSadaf Ebrahimi--
40*287e80b3SSadaf Ebrahimi#include <stdlib.h>
41*287e80b3SSadaf Ebrahimi#include <unistd.h>
42*287e80b3SSadaf Ebrahimi#include <sys/wait.h>
43*287e80b3SSadaf Ebrahimi
44*287e80b3SSadaf Ebrahimi#include <tracefs.h>
45*287e80b3SSadaf Ebrahimi
46*287e80b3SSadaf Ebrahimistatic struct tep_event *open_event;
47*287e80b3SSadaf Ebrahimistatic struct tep_format_field *file_field;
48*287e80b3SSadaf Ebrahimi
49*287e80b3SSadaf Ebrahimistatic int callback(struct tep_event *event, struct tep_record *record,
50*287e80b3SSadaf Ebrahimi		    int cpu, void *data)
51*287e80b3SSadaf Ebrahimi{
52*287e80b3SSadaf Ebrahimi	struct trace_seq seq;
53*287e80b3SSadaf Ebrahimi
54*287e80b3SSadaf Ebrahimi	trace_seq_init(&seq);
55*287e80b3SSadaf Ebrahimi	tep_print_event(event->tep, &seq, record, "%d-%s: ", TEP_PRINT_PID, TEP_PRINT_COMM);
56*287e80b3SSadaf Ebrahimi
57*287e80b3SSadaf Ebrahimi	if (event->id == open_event->id) {
58*287e80b3SSadaf Ebrahimi		trace_seq_puts(&seq, "open file='");
59*287e80b3SSadaf Ebrahimi		tep_print_field(&seq, record->data, file_field);
60*287e80b3SSadaf Ebrahimi		trace_seq_puts(&seq, "'\n");
61*287e80b3SSadaf Ebrahimi	}
62*287e80b3SSadaf Ebrahimi
63*287e80b3SSadaf Ebrahimi	trace_seq_terminate(&seq);
64*287e80b3SSadaf Ebrahimi	trace_seq_do_printf(&seq);
65*287e80b3SSadaf Ebrahimi	trace_seq_destroy(&seq);
66*287e80b3SSadaf Ebrahimi
67*287e80b3SSadaf Ebrahimi	return 0;
68*287e80b3SSadaf Ebrahimi}
69*287e80b3SSadaf Ebrahimi
70*287e80b3SSadaf Ebrahimistatic pid_t run_exec(char **argv, char **env)
71*287e80b3SSadaf Ebrahimi{
72*287e80b3SSadaf Ebrahimi	pid_t pid;
73*287e80b3SSadaf Ebrahimi
74*287e80b3SSadaf Ebrahimi	pid = fork();
75*287e80b3SSadaf Ebrahimi	if (pid)
76*287e80b3SSadaf Ebrahimi		return pid;
77*287e80b3SSadaf Ebrahimi
78*287e80b3SSadaf Ebrahimi	execve(argv[0], argv, env);
79*287e80b3SSadaf Ebrahimi	perror("exec");
80*287e80b3SSadaf Ebrahimi	exit(-1);
81*287e80b3SSadaf Ebrahimi}
82*287e80b3SSadaf Ebrahimi
83*287e80b3SSadaf Ebrahimiconst char *myprobe = "my_eprobes";
84*287e80b3SSadaf Ebrahimi
85*287e80b3SSadaf Ebrahimiint main (int argc, char **argv, char **env)
86*287e80b3SSadaf Ebrahimi{
87*287e80b3SSadaf Ebrahimi	struct tracefs_dynevent *eprobe;
88*287e80b3SSadaf Ebrahimi	struct tracefs_instance *instance;
89*287e80b3SSadaf Ebrahimi	struct tep_handle *tep;
90*287e80b3SSadaf Ebrahimi	const char *sysnames[] = { myprobe, NULL };
91*287e80b3SSadaf Ebrahimi	pid_t pid;
92*287e80b3SSadaf Ebrahimi
93*287e80b3SSadaf Ebrahimi	if (argc < 2) {
94*287e80b3SSadaf Ebrahimi		printf("usage: %s command\n", argv[0]);
95*287e80b3SSadaf Ebrahimi		exit(-1);
96*287e80b3SSadaf Ebrahimi	}
97*287e80b3SSadaf Ebrahimi
98*287e80b3SSadaf Ebrahimi	instance = tracefs_instance_create("exec_open");
99*287e80b3SSadaf Ebrahimi	if (!instance) {
100*287e80b3SSadaf Ebrahimi		perror("creating instance");
101*287e80b3SSadaf Ebrahimi		exit(-1);
102*287e80b3SSadaf Ebrahimi	}
103*287e80b3SSadaf Ebrahimi
104*287e80b3SSadaf Ebrahimi	tracefs_dynevent_destroy_all(TRACEFS_DYNEVENT_EPROBE, true);
105*287e80b3SSadaf Ebrahimi
106*287e80b3SSadaf Ebrahimi	eprobe = tracefs_eprobe_alloc(myprobe, "sopen", "syscalls", "sys_enter_openat2",
107*287e80b3SSadaf Ebrahimi				      "file=+0($filename):ustring");
108*287e80b3SSadaf Ebrahimi	if (!eprobe) {
109*287e80b3SSadaf Ebrahimi		perror("allocating event probe");
110*287e80b3SSadaf Ebrahimi		exit(-1);
111*287e80b3SSadaf Ebrahimi	}
112*287e80b3SSadaf Ebrahimi
113*287e80b3SSadaf Ebrahimi	if (tracefs_dynevent_create(eprobe)) {
114*287e80b3SSadaf Ebrahimi		perror("creating event probe");
115*287e80b3SSadaf Ebrahimi		exit(-1);
116*287e80b3SSadaf Ebrahimi	}
117*287e80b3SSadaf Ebrahimi
118*287e80b3SSadaf Ebrahimi	tep = tracefs_local_events_system(NULL, sysnames);
119*287e80b3SSadaf Ebrahimi	if (!tep) {
120*287e80b3SSadaf Ebrahimi		perror("reading events");
121*287e80b3SSadaf Ebrahimi		exit(-1);
122*287e80b3SSadaf Ebrahimi	}
123*287e80b3SSadaf Ebrahimi
124*287e80b3SSadaf Ebrahimi	open_event = tep_find_event_by_name(tep, myprobe, "sopen");
125*287e80b3SSadaf Ebrahimi	file_field = tep_find_field(open_event, "file");
126*287e80b3SSadaf Ebrahimi
127*287e80b3SSadaf Ebrahimi	tracefs_event_enable(instance, myprobe, "sopen");
128*287e80b3SSadaf Ebrahimi	pid = run_exec(&argv[1], env);
129*287e80b3SSadaf Ebrahimi
130*287e80b3SSadaf Ebrahimi	/* Let the child start to run */
131*287e80b3SSadaf Ebrahimi	sched_yield();
132*287e80b3SSadaf Ebrahimi
133*287e80b3SSadaf Ebrahimi	do {
134*287e80b3SSadaf Ebrahimi		tracefs_load_cmdlines(NULL, tep);
135*287e80b3SSadaf Ebrahimi		tracefs_iterate_raw_events(tep, instance, NULL, 0, callback, NULL);
136*287e80b3SSadaf Ebrahimi	} while (waitpid(pid, NULL, WNOHANG) != pid);
137*287e80b3SSadaf Ebrahimi
138*287e80b3SSadaf Ebrahimi	/* Will disable the events */
139*287e80b3SSadaf Ebrahimi	tracefs_dynevent_destroy(eprobe, true);
140*287e80b3SSadaf Ebrahimi	tracefs_dynevent_free(eprobe);
141*287e80b3SSadaf Ebrahimi	tracefs_instance_destroy(instance);
142*287e80b3SSadaf Ebrahimi	tep_free(tep);
143*287e80b3SSadaf Ebrahimi
144*287e80b3SSadaf Ebrahimi	return 0;
145*287e80b3SSadaf Ebrahimi}
146*287e80b3SSadaf Ebrahimi--
147*287e80b3SSadaf Ebrahimi
148*287e80b3SSadaf EbrahimiFILES
149*287e80b3SSadaf Ebrahimi-----
150*287e80b3SSadaf Ebrahimi[verse]
151*287e80b3SSadaf Ebrahimi--
152*287e80b3SSadaf Ebrahimi*tracefs.h*
153*287e80b3SSadaf Ebrahimi	Header file to include in order to have access to the library APIs.
154*287e80b3SSadaf Ebrahimi*-ltracefs*
155*287e80b3SSadaf Ebrahimi	Linker switch to add when building a program that uses the library.
156*287e80b3SSadaf Ebrahimi--
157*287e80b3SSadaf Ebrahimi
158*287e80b3SSadaf EbrahimiSEE ALSO
159*287e80b3SSadaf Ebrahimi--------
160*287e80b3SSadaf Ebrahimi*libtracefs*(3),
161*287e80b3SSadaf Ebrahimi*libtraceevent*(3),
162*287e80b3SSadaf Ebrahimi*trace-cmd*(1)
163*287e80b3SSadaf Ebrahimi
164*287e80b3SSadaf EbrahimiAUTHOR
165*287e80b3SSadaf Ebrahimi------
166*287e80b3SSadaf Ebrahimi[verse]
167*287e80b3SSadaf Ebrahimi--
168*287e80b3SSadaf Ebrahimi*Steven Rostedt* <[email protected]>
169*287e80b3SSadaf Ebrahimi*Tzvetomir Stoyanov* <[email protected]>
170*287e80b3SSadaf Ebrahimi--
171*287e80b3SSadaf Ebrahimi
172*287e80b3SSadaf EbrahimiREPORTING BUGS
173*287e80b3SSadaf Ebrahimi--------------
174*287e80b3SSadaf EbrahimiReport bugs to  <[email protected]>
175*287e80b3SSadaf Ebrahimi
176*287e80b3SSadaf EbrahimiLICENSE
177*287e80b3SSadaf Ebrahimi-------
178*287e80b3SSadaf Ebrahimilibtracefs is Free Software licensed under the GNU LGPL 2.1
179*287e80b3SSadaf Ebrahimi
180*287e80b3SSadaf EbrahimiRESOURCES
181*287e80b3SSadaf Ebrahimi---------
182*287e80b3SSadaf Ebrahimihttps://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/
183*287e80b3SSadaf Ebrahimi
184*287e80b3SSadaf EbrahimiCOPYING
185*287e80b3SSadaf Ebrahimi-------
186*287e80b3SSadaf EbrahimiCopyright \(C) 2021 VMware, Inc. Free use of this software is granted under
187*287e80b3SSadaf Ebrahimithe terms of the GNU Public License (GPL).
188