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