1libtracefs(3) 2============= 3 4NAME 5---- 6tracefs_uprobe_alloc,tracefs_uretprobe_alloc - Allocate new user (return) probe 7 8SYNOPSIS 9-------- 10[verse] 11-- 12*#include <tracefs.h>* 13 14struct tracefs_dynevent pass:[*] 15*tracefs_uprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, 16 const char pass:[*]_file_, unsigned long long _offset_, const char pass:[*]_fetchargs_) 17struct tracefs_dynevent pass:[*] 18*tracefs_uretprobe_alloc*(const char pass:[*]_system_, const char pass:[*]_event_, 19 const char pass:[*]_file_, unsigned long long _offset_, const char pass:[*]_fetchargs_) 20-- 21 22DESCRIPTION 23----------- 24*tracefs_uprobe_alloc*() allocates a new uprobe context. It will be in the _system_ group 25(or uprobes if _system_ is NULL) and with _event_ name. The uprobe will be attached to _offset_ 26within the _file_. The list of arguments, described in _fetchargs_, will be fetched with the uprobe. 27The returned pointer to the user probe context must be freed with *tracefs_dynevent_free*(). 28The ubrobe is not configured in the system, tracefs_dynevent_* set of APIs can be used to configure 29it. 30 31The *tracefs_uretprobe_alloc*() behaves the same as *tracefs_uprobe_alloc*(), the only difference is 32that it allocates context to user return probe (uretprobe). 33 34RETURN VALUE 35------------ 36The *tracefs_uprobe_alloc*() and *tracefs_uretprobe_alloc*() APIs return a pointer to an allocated 37tracefs_dynevent structure, describing the user probe. This pointer must be freed with 38*tracefs_dynevent_free*(3). Note, this only allocates a descriptor representing the uprobe. It does 39not modify the running system. On error NULL is returned. 40 41EXAMPLE 42------- 43[source,c] 44-- 45 46#include <stdlib.h> 47#include <unistd.h> 48#include <sys/wait.h> 49 50#include <tracefs.h> 51 52static int callback(struct tep_event *event, struct tep_record *record, 53 int cpu, void *data) 54{ 55 struct trace_seq seq; 56 57 trace_seq_init(&seq); 58 tep_print_event(event->tep, &seq, record, "%d-%s: %s", 59 TEP_PRINT_PID, TEP_PRINT_COMM, TEP_PRINT_NAME); 60 trace_seq_puts(&seq, "'\n"); 61 62 trace_seq_terminate(&seq); 63 trace_seq_do_printf(&seq); 64 trace_seq_destroy(&seq); 65 66 return 0; 67} 68 69static pid_t run_exec(char **argv, char **env) 70{ 71 pid_t pid; 72 73 pid = fork(); 74 if (pid) 75 return pid; 76 77 execve(argv[0], argv, env); 78 perror("exec"); 79 exit(-1); 80} 81 82const char *myprobe = "my_urobes"; 83 84int main (int argc, char **argv, char **env) 85{ 86 struct tracefs_dynevent *uprobe, *uretprobe; 87 struct tep_handle *tep; 88 struct tracefs_instance *instance; 89 const char *sysnames[] = { myprobe, NULL }; 90 long addr; 91 pid_t pid; 92 93 if (argc < 3) { 94 printf("usage: %s file_offset command\n", argv[0]); 95 exit(-1); 96 } 97 addr = strtol(argv[1], NULL, 0); 98 99 instance = tracefs_instance_create("exec_open"); 100 if (!instance) { 101 perror("creating instance"); 102 exit(-1); 103 } 104 105 tracefs_dynevent_destroy_all(TRACEFS_DYNEVENT_UPROBE|TRACEFS_DYNEVENT_URETPROBE, true); 106 107 uprobe = tracefs_uprobe_alloc(myprobe, "user_probe", argv[2], addr, NULL); 108 uretprobe = tracefs_uretprobe_alloc(myprobe, "user_retprobe", argv[2], addr, NULL); 109 if (!uprobe || !uretprobe) { 110 perror("allocating user probes"); 111 exit(-1); 112 } 113 114 if (tracefs_dynevent_create(uprobe) || 115 tracefs_dynevent_create(uretprobe)) { 116 perror("creating user probes"); 117 exit(-1); 118 } 119 120 tep = tracefs_local_events_system(NULL, sysnames); 121 if (!tep) { 122 perror("reading events"); 123 exit(-1); 124 } 125 126 tracefs_event_enable(instance, myprobe, "user_probe"); 127 tracefs_event_enable(instance, myprobe, "user_retprobe"); 128 129 pid = run_exec(&argv[2], env); 130 131 /* Let the child start to run */ 132 sched_yield(); 133 134 do { 135 tracefs_load_cmdlines(NULL, tep); 136 tracefs_iterate_raw_events(tep, instance, NULL, 0, callback, NULL); 137 } while (waitpid(pid, NULL, WNOHANG) != pid); 138 139 /* disable and destroy the events */ 140 tracefs_dynevent_destroy(uprobe, true); 141 tracefs_dynevent_destroy(uretprobe, true); 142 tracefs_dynevent_free(uprobe); 143 tracefs_dynevent_free(uretprobe); 144 tracefs_instance_destroy(instance); 145 146 return 0; 147} 148-- 149 150FILES 151----- 152[verse] 153-- 154*tracefs.h* 155 Header file to include in order to have access to the library APIs. 156*-ltracefs* 157 Linker switch to add when building a program that uses the library. 158-- 159 160SEE ALSO 161-------- 162*libtracefs*(3), 163*libtraceevent*(3), 164*trace-cmd*(1) 165 166AUTHOR 167------ 168[verse] 169-- 170*Steven Rostedt* <[email protected]> 171*Tzvetomir Stoyanov* <[email protected]> 172-- 173 174REPORTING BUGS 175-------------- 176Report bugs to <[email protected]> 177 178LICENSE 179------- 180libtracefs is Free Software licensed under the GNU LGPL 2.1 181 182RESOURCES 183--------- 184https://git.kernel.org/pub/scm/libs/libtrace/libtracefs.git/ 185 186COPYING 187------- 188Copyright \(C) 2022 VMware, Inc. Free use of this software is granted under 189the terms of the GNU Public License (GPL). 190