| libtracefs(3) |
| ============= |
| |
| NAME |
| ---- |
| tracefs_uprobe_alloc,tracefs_uretprobe_alloc - Allocate new user (return) probe |
| |
| SYNOPSIS |
| -------- |
| [verse] |
| -- |
| *#include <tracefs.h>* |
| |
| struct tracefs_dynevent pass:[*] |
| *tracefs_uprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_, unsigned long long _offset_, const char pass:[*]_fetchargs_) |
| struct tracefs_dynevent pass:[*] |
| *tracefs_uretprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, |
| const char pass:[*]_file_, unsigned long long _offset_, const char pass:[*]_fetchargs_) |
| -- |
| |
| DESCRIPTION |
| ----------- |
| *tracefs_uprobe_alloc*() allocates a new uprobe context. It will be in the _system_ group |
| (or uprobes if _system_ is NULL) and with _event_ name. The uprobe will be attached to _offset_ |
| within the _file_. The list of arguments, described in _fetchargs_, will be fetched with the uprobe. |
| The returned pointer to the user probe context must be freed with *tracefs_dynevent_free*(). |
| The ubrobe is not configured in the system, tracefs_dynevent_* set of APIs can be used to configure |
| it. |
| |
| The *tracefs_uretprobe_alloc*() behaves the same as *tracefs_uprobe_alloc*(), the only difference is |
| that it allocates context to user return probe (uretprobe). |
| |
| RETURN VALUE |
| ------------ |
| The *tracefs_uprobe_alloc*() and *tracefs_uretprobe_alloc*() APIs return a pointer to an allocated |
| tracefs_dynevent structure, describing the user probe. This pointer must be freed with |
| *tracefs_dynevent_free*(3). Note, this only allocates a descriptor representing the uprobe. It does |
| not modify the running system. On error NULL is returned. |
| |
| EXAMPLE |
| ------- |
| [source,c] |
| -- |
| |
| #include <stdlib.h> |
| #include <unistd.h> |
| #include <sys/wait.h> |
| |
| #include <tracefs.h> |
| |
| 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: %s", |
| TEP_PRINT_PID, TEP_PRINT_COMM, TEP_PRINT_NAME); |
| trace_seq_puts(&seq, "'\n"); |
| |
| trace_seq_terminate(&seq); |
| trace_seq_do_printf(&seq); |
| 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 *myprobe = "my_urobes"; |
| |
| int main (int argc, char **argv, char **env) |
| { |
| struct tracefs_dynevent *uprobe, *uretprobe; |
| struct tep_handle *tep; |
| struct tracefs_instance *instance; |
| const char *sysnames[] = { myprobe, NULL }; |
| long addr; |
| pid_t pid; |
| |
| if (argc < 3) { |
| printf("usage: %s file_offset command\n", argv[0]); |
| exit(-1); |
| } |
| addr = strtol(argv[1], NULL, 0); |
| |
| instance = tracefs_instance_create("exec_open"); |
| if (!instance) { |
| perror("creating instance"); |
| exit(-1); |
| } |
| |
| tracefs_dynevent_destroy_all(TRACEFS_DYNEVENT_UPROBE|TRACEFS_DYNEVENT_URETPROBE, true); |
| |
| uprobe = tracefs_uprobe_alloc(myprobe, "user_probe", argv[2], addr, NULL); |
| uretprobe = tracefs_uretprobe_alloc(myprobe, "user_retprobe", argv[2], addr, NULL); |
| if (!uprobe || !uretprobe) { |
| perror("allocating user probes"); |
| exit(-1); |
| } |
| |
| if (tracefs_dynevent_create(uprobe) || |
| tracefs_dynevent_create(uretprobe)) { |
| perror("creating user probes"); |
| exit(-1); |
| } |
| |
| tep = tracefs_local_events_system(NULL, sysnames); |
| if (!tep) { |
| perror("reading events"); |
| exit(-1); |
| } |
| |
| tracefs_event_enable(instance, myprobe, "user_probe"); |
| tracefs_event_enable(instance, myprobe, "user_retprobe"); |
| |
| pid = run_exec(&argv[2], 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); |
| |
| /* disable and destroy the events */ |
| tracefs_dynevent_destroy(uprobe, true); |
| tracefs_dynevent_destroy(uretprobe, true); |
| tracefs_dynevent_free(uprobe); |
| tracefs_dynevent_free(uretprobe); |
| tracefs_instance_destroy(instance); |
| |
| 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> |
| -- |
| |
| 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) 2022 VMware, Inc. Free use of this software is granted under |
| the terms of the GNU Public License (GPL). |