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

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