# tracefs_uprobe_alloc

## NAME



           tracefs_uprobe_alloc, tracefs_uretprobe_alloc - Allocate new user
           (return) probe
    


## SYNOPSIS



           **#include <tracefs.h>**
    
           struct tracefs_dynevent *
           **tracefs_uprobe_alloc**(const char *_system_ , const char *_event_ ,
                                const char *_file_ , unsigned long long _offset_ , const char *_fetchargs_)
           struct tracefs_dynevent *
           **tracefs_uretprobe_alloc**(const char *_system_ , const char *_event_ ,
                                const char *_file_ , unsigned long long _offset_ , const char *_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



               #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



               **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.
    


## 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).
    


## NOTES



            1. rostedt@goodmis.org
               mailto:rostedt@goodmis.org
    
            2. tz.stoyanov@gmail.com
               mailto:tz.stoyanov@gmail.com
    
            3. linux-trace-devel@vger.kernel.org
               mailto:linux-trace-devel@vger.kernel.org
    


* * *