contents/using-lttng/instrumenting/prebuilt-ust-helpers/liblttng-ust-libc-pthread-wrapper.md

   1 ---
   2 id: liblttng‑ust‑libc‑pthread-wrapper
   3 ---
   4
   5 `liblttng-ust-libc-wrapper.so` and `liblttng-ust-pthread-wrapper.so`
   6 can add instrumentation to respectively some C standard library and
   7 POSIX threads functions.
   8
   9 The following functions are traceable by `liblttng-ust-libc-wrapper.so`:
  10
  11 <table class="func-desc">
  12     <thead>
  13         <tr>
  14             <th><abbr title="Tracepoint">TP</abbr> provider name</th>
  15             <th><abbr title="Tracepoint">TP</abbr> name</th>
  16             <th>Instrumented function</th>
  17         </tr>
  18     </thead>
  19     <tbody>
  20         <tr>
  21             <td rowspan="6">
  22                 <code class="no-bg">ust_libc</code>
  23             </td>
  24             <td>
  25                 <code class="no-bg">malloc</code>
  26             </td>
  27             <td>
  28                 <code class="no-bg">malloc()</code>
  29             </td>
  30         </tr>
  31         <tr>
  32             <td>
  33                 <code class="no-bg">calloc</code>
  34             </td>
  35             <td>
  36                 <code class="no-bg">calloc()</code>
  37             </td>
  38         </tr>
  39         <tr>
  40             <td>
  41                 <code class="no-bg">realloc</code>
  42             </td>
  43             <td>
  44                 <code class="no-bg">realloc()</code>
  45             </td>
  46         </tr>
  47         <tr>
  48             <td>
  49                 <code class="no-bg">free</code>
  50             </td>
  51             <td>
  52                 <code class="no-bg">free()</code>
  53             </td>
  54         </tr>
  55         <tr>
  56             <td>
  57                 <code class="no-bg">memalign</code>
  58             </td>
  59             <td>
  60                 <code class="no-bg">memalign()</code>
  61             </td>
  62         </tr>
  63         <tr>
  64             <td>
  65                 <code class="no-bg">posix_memalign</code>
  66             </td>
  67             <td>
  68                 <code class="no-bg">posix_memalign()</code>
  69             </td>
  70         </tr>
  71     </tbody>
  72 </table>
  73
  74 The following functions are traceable by
  75 `liblttng-ust-pthread-wrapper.so`:
  76
  77 <table class="func-desc">
  78     <thead>
  79         <tr>
  80             <th><abbr title="Tracepoint">TP</abbr> provider name</th>
  81             <th><abbr title="Tracepoint">TP</abbr> name</th>
  82             <th>Instrumented function</th>
  83         </tr>
  84     </thead>
  85     <tbody>
  86         <tr>
  87             <td rowspan="4">
  88                 <code class="no-bg">ust_pthread</code>
  89             </td>
  90             <td>
  91                 <code class="no-bg">pthread_mutex_lock_req</code>
  92             </td>
  93             <td>
  94                 <code class="no-bg">pthread_mutex_lock()</code> (request time)
  95             </td>
  96         </tr>
  97         <tr>
  98             <td>
  99                 <code class="no-bg">pthread_mutex_lock_acq</code>
 100             </td>
 101             <td>
 102                 <code class="no-bg">pthread_mutex_lock()</code> (acquire time)
 103             </td>
 104         </tr>
 105         <tr>
 106             <td>
 107                 <code class="no-bg">pthread_mutex_trylock</code>
 108             </td>
 109             <td>
 110                 <code class="no-bg">pthread_mutex_trylock()</code>
 111             </td>
 112         </tr>
 113         <tr>
 114             <td>
 115                 <code class="no-bg">pthread_mutex_unlock</code>
 116             </td>
 117             <td>
 118                 <code class="no-bg">pthread_mutex_unlock()</code>
 119             </td>
 120         </tr>
 121     </tbody>
 122 </table>
 123
 124 All tracepoints have fields corresponding to the arguments of the
 125 function they instrument.
 126
 127 To use one or the other with any user application, independently of
 128 how the latter is built, do:
 129
 130 <pre class="term">
 131 LD_PRELOAD=liblttng-ust-libc-wrapper.so my-app
 132 </pre>
 133
 134 or
 135
 136 <pre class="term">
 137 LD_PRELOAD=liblttng-ust-pthread-wrapper.so my-app
 138 </pre>
 139
 140 To use both, do:
 141
 142 <pre class="term">
 143 LD_PRELOAD="liblttng-ust-libc-wrapper.so liblttng-ust-pthread-wrapper.so" my-app
 144 </pre>
 145
 146 When the shared object is preloaded, it effectively replaces the
 147 functions listed in the above tables by wrappers which add tracepoints
 148 and call the replaced functions.
 149
 150 Of course, like any other tracepoint, the ones above need to be enabled
 151 in order for LTTng-UST to generate events. This is done using the
 152 `lttng` command line tool
 153 (see [Controlling tracing](#doc-controlling-tracing)).