284 lines
9.9 KiB
Plaintext
284 lines
9.9 KiB
Plaintext
libtracefs(3)
|
|
=============
|
|
|
|
NAME
|
|
----
|
|
tracefs_dynevent_create, tracefs_dynevent_destroy, tracefs_dynevent_destroy_all,
|
|
tracefs_dynevent_free, tracefs_dynevent_list_free, tracefs_dynevent_get, tracefs_dynevent_get_all,
|
|
tracefs_dynevent_info, tracefs_dynevent_get_event - Create, destroy, free and get dynamic events.
|
|
|
|
SYNOPSIS
|
|
--------
|
|
[verse]
|
|
--
|
|
*#include <tracefs.h>*
|
|
|
|
struct *tracefs_dynevent*;
|
|
enum *tracefs_dynevent_type*;
|
|
int *tracefs_dynevent_create*(struct tracefs_dynevent pass:[*]_devent_);
|
|
int *tracefs_dynevent_destroy*(struct tracefs_dynevent pass:[*]_devent_, bool _force_);
|
|
int *tracefs_dynevent_destroy_all*(unsigned int _types_, bool _force_);
|
|
void *tracefs_dynevent_free*(struct tracefs_dynevent pass:[*]_devent_);
|
|
void *tracefs_dynevent_list_free*(struct tracefs_dynevent pass:[*]pass:[*]_events_);
|
|
struct tracefs_dynevent pass:[*]*tracefs_dynevent_get*(enum tracefs_dynevent_type _type_, const char pass:[*]_system_, const char pass:[*]_event_);
|
|
struct tracefs_dynevent pass:[*]pass:[*]*tracefs_dynevent_get_all*(unsigned int _types_, const char pass:[*]_system_);
|
|
enum tracefs_dynevent_type *tracefs_dynevent_info*(struct tracefs_dynevent pass:[*]_dynevent_, char pass:[*]pass:[*]_system_, char pass:[*]pass:[*]_event_, char pass:[*]pass:[*]_prefix_, char pass:[*]pass:[*]_addr_, char pass:[*]pass:[*]_format_);
|
|
struct tep_event pass:[*]*tracefs_dynevent_get_event*(struct tep_handle pass:[*]_tep_, struct tracefs_dynevent pass:[*]_dynevent_);
|
|
--
|
|
|
|
DESCRIPTION
|
|
-----------
|
|
|
|
The *tracefs_dynevent_create*() function creates dynamic event _devent_ in the system.
|
|
|
|
The *tracefs_dynevent_destroy*() function removes dynamic event _devent_ from the system. If _force_
|
|
is true, the function will attempt to disable all events in all trace instances, before removing
|
|
the dynamic event. The _devent_ context is not freed, use *tracefs_dynevent_free*() to free it.
|
|
|
|
The *tracefs_dynevent_destroy_all*() function removes all dynamic events of given types from the
|
|
system. The _types_ parameter is a type of specific dynamic event, or a bitmask of dynamic events
|
|
types *tracefs_dynevent_type*, that will be removed. If _types_ is 0, dynamic events from all types
|
|
will be removed. If _force_ is true, the function will attempt to disable all events in all trace
|
|
instances, before removing the dynamic events.
|
|
|
|
The *tracefs_dynevent_get*() function allocates and returns a single instance of a dynamic
|
|
event that matches the given *type*, *system* and *event* that is passed to it. NULL is returned
|
|
if there is no match. The returned event is what is found in the system, and must be freed
|
|
with *tracefs_dynevent_free*(). If *system* is NULL, then the first *event* of any system
|
|
of the given type that has the name of *event* will be returned.
|
|
|
|
The *tracefs_dynevent_get_all*() function allocates and returns an array of pointers to dynamic
|
|
events of given types that exist in the system. The last element of the array is a NULL pointer.
|
|
The array must be freed with *tracefs_dynevent_list_free*(). If there are no events a NULL pointer is
|
|
returned. The _types_ parameter is a type of specific dynamic event, or a bitmask of dynamic events
|
|
types *tracefs_dynevent_type*, that will be retrieved. If _types_ is 0, dynamic events from all
|
|
types will be retrieved.
|
|
|
|
The *tracefs_dynevent_free*() function frees a dynamic event context _devent_.
|
|
|
|
The *tracefs_dynevent_list_free*() function frees an array of pointers to dynamic event, returned
|
|
by *tracefs_dynevent_get_all()* API.
|
|
|
|
The *tracefs_dynevent_info*() function returns the type and information of a given dynamic event
|
|
_dynevent_. If any of the _system_, _event_, _prefix_, _addr_ or _format_ arguments are not NULL,
|
|
then strings are allocated and returned back via these arguments. The _system_ and _event_ holds the
|
|
system and the name of the dynamic event. If _prefix_ is non NULL, then it will hold an allocated
|
|
string that holds the prefix portion of the dynamic event (the content up to the ":", exluding it).
|
|
If _addr_ is non NULL, it will hold the address or function that the dynamic event is attached to,
|
|
if relevant for this event type. If _format_ is non NULL, it will hold the format string of the
|
|
dynamic event. Note, that the content in _group_, _event_, _prefix_, _addr_, and _format_ must be
|
|
freed with free(3) if they are set.
|
|
|
|
The *tracefs_dynevent_get_event*() function returns a tep event, describing the given dynamic event.
|
|
The API detects any newly created or removed dynamic events. The returned pointer to tep event is
|
|
controlled by @tep and must not be freed.
|
|
|
|
RETURN VALUE
|
|
------------
|
|
|
|
*tracefs_dynevent_create*() returns 0 on success, or -1 on error. If a parsing error occurs then
|
|
*tracefs_error_last*(3) may be used to retrieve the error message explaining the parsing issue.
|
|
|
|
*tracefs_dynevent_destroy*() and *tracefs_dynevent_destroy_all*() return 0 on success, or -1 on
|
|
error. If _force_ is enabled, the functions may fail on disabling the events.
|
|
|
|
*tracefs_dynevent_get*() function returns an allocated dynamic event from the system that matches
|
|
the type, system and event given.
|
|
|
|
*tracefs_dynevent_get_all*() function returns allocated array of pointers to dynamic events, or NULL
|
|
in case of an error or in case there are no events in the system. That array must be freed by
|
|
*tracefs_dynevent_list_free*().
|
|
|
|
*tracefs_dynevent_info*() returns the type of the given dynamic event or TRACEFS_DYNEVENT_UNKNOWN
|
|
on error. If _system_, _event_, _prefix_, _addr_, or _format_ are non NULL, they will contain
|
|
allocated strings that must be freed by free(3).
|
|
|
|
The *tracefs_dynevent_get_event*() function returns a pointer to a tep event or NULL in case of an
|
|
error or if the requested dynamic event is missing. The returned pointer to tep event is controlled
|
|
by @tep and must not be freed.
|
|
|
|
ERRORS
|
|
------
|
|
The following errors are for all the above calls:
|
|
|
|
*ENODEV* dynamic events of requested type are not configured for the running kernel.
|
|
|
|
*ENOMEM* Memory allocation error.
|
|
|
|
*tracefs_dynevent_create*() can fail with the following errors:
|
|
|
|
*EINVAL* Most likely a parsing error occurred (use *tracefs_error_last*(3) to possibly
|
|
see what that error was).
|
|
|
|
Other errors may also happen caused by internal system calls.
|
|
|
|
EXAMPLE
|
|
-------
|
|
[source,c]
|
|
--
|
|
#include <stdlib.h>
|
|
#include <unistd.h>
|
|
#include <sys/wait.h>
|
|
|
|
#include <tracefs.h>
|
|
|
|
static struct tep_event *open_event;
|
|
static struct tep_format_field *file_field;
|
|
|
|
static struct tep_event *openret_event;
|
|
static struct tep_format_field *ret_field;
|
|
|
|
static int callback(struct tep_event *event, struct tep_record *record,
|
|
int cpu, void *data)
|
|
{
|
|
struct trace_seq seq;
|
|
|
|
trace_seq_init(&seq);
|
|
tep_print_event(event->tep, &seq, record, "%d-%s: ", TEP_PRINT_PID, TEP_PRINT_COMM);
|
|
|
|
if (event->id == open_event->id) {
|
|
trace_seq_puts(&seq, "open file='");
|
|
tep_print_field(&seq, record->data, file_field);
|
|
trace_seq_puts(&seq, "'\n");
|
|
} else if (event->id == openret_event->id) {
|
|
unsigned long long ret;
|
|
tep_read_number_field(ret_field, record->data, &ret);
|
|
trace_seq_printf(&seq, "open ret=%lld\n", ret);
|
|
} else {
|
|
goto out;
|
|
}
|
|
|
|
trace_seq_terminate(&seq);
|
|
trace_seq_do_printf(&seq);
|
|
out:
|
|
trace_seq_destroy(&seq);
|
|
|
|
return 0;
|
|
}
|
|
|
|
static pid_t run_exec(char **argv, char **env)
|
|
{
|
|
pid_t pid;
|
|
|
|
pid = fork();
|
|
if (pid)
|
|
return pid;
|
|
|
|
execve(argv[0], argv, env);
|
|
perror("exec");
|
|
exit(-1);
|
|
}
|
|
|
|
const char *mykprobe = "my_kprobes";
|
|
|
|
int main (int argc, char **argv, char **env)
|
|
{
|
|
struct tracefs_dynevent *kprobe, *kretprobe;
|
|
const char *sysnames[] = { mykprobe, NULL };
|
|
struct tracefs_instance *instance;
|
|
struct tep_handle *tep;
|
|
pid_t pid;
|
|
|
|
if (argc < 2) {
|
|
printf("usage: %s command\n", argv[0]);
|
|
exit(-1);
|
|
}
|
|
|
|
instance = tracefs_instance_create("exec_open");
|
|
if (!instance) {
|
|
perror("creating instance");
|
|
exit(-1);
|
|
}
|
|
|
|
tracefs_dynevent_destroy_all(TRACEFS_DYNEVENT_KPROBE | TRACEFS_DYNEVENT_KRETPROBE, true);
|
|
|
|
kprobe = tracefs_kprobe_alloc(mykprobe, "open", "do_sys_openat2",
|
|
"file=+0($arg2):ustring flags=+0($arg3):x64 mode=+8($arg3):x64\n");
|
|
kretprobe = tracefs_kretprobe_alloc(mykprobe, "openret", "do_sys_openat2", "ret=%ax", 0);
|
|
if (!kprobe || !kretprobe) {
|
|
perror("allocating dynamic events");
|
|
exit(-1);
|
|
}
|
|
|
|
if (tracefs_dynevent_create(kprobe) || tracefs_dynevent_create(kretprobe)){
|
|
char *err = tracefs_error_last(NULL);
|
|
perror("Failed to create kprobes:");
|
|
if (err && strlen(err))
|
|
fprintf(stderr, "%s\n", err);
|
|
exit(-1);
|
|
}
|
|
|
|
tep = tracefs_local_events_system(NULL, sysnames);
|
|
if (!tep) {
|
|
perror("reading events");
|
|
exit(-1);
|
|
}
|
|
open_event = tep_find_event_by_name(tep, mykprobe, "open");
|
|
file_field = tep_find_field(open_event, "file");
|
|
|
|
openret_event = tep_find_event_by_name(tep, mykprobe, "openret");
|
|
ret_field = tep_find_field(openret_event, "ret");
|
|
|
|
tracefs_event_enable(instance, mykprobe, NULL);
|
|
pid = run_exec(&argv[1], env);
|
|
|
|
/* Let the child start to run */
|
|
sched_yield();
|
|
|
|
do {
|
|
tracefs_load_cmdlines(NULL, tep);
|
|
tracefs_iterate_raw_events(tep, instance, NULL, 0, callback, NULL);
|
|
} while (waitpid(pid, NULL, WNOHANG) != pid);
|
|
|
|
/* Will disable the events */
|
|
tracefs_dynevent_destroy_all(TRACEFS_DYNEVENT_KPROBE | TRACEFS_DYNEVENT_KRETPROBE, true);
|
|
tracefs_dynevent_free(kprobe);
|
|
tracefs_dynevent_free(kretprobe);
|
|
tracefs_instance_destroy(instance);
|
|
tep_free(tep);
|
|
|
|
return 0;
|
|
}
|
|
--
|
|
|
|
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>
|
|
*Yordan Karadzhov* <y.karadz@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) 2021 VMware, Inc. Free use of this software is granted under
|
|
the terms of the GNU Public License (GPL).
|