contents/reference/lttng-ust/liblttng-ust/liblttng-ust-tp-fields.md

   1 ---
   2 id: liblttng-ust-tp-fields
   3 ---
   4
   5 The available macros to define tracepoint fields, which should be listed
   6 within `TP_FIELDS()` in `TRACEPOINT_EVENT()`, are:
   7
   8 <div class="table">
   9 <table class="func-desc">
  10     <thead>
  11         <tr>
  12             <th>Macro</th>
  13             <th>Description/arguments</th>
  14         </tr>
  15     </thead>
  16     <tbody>
  17         <tr>
  18             <td>
  19                 <ul>
  20                     <li><code class="no-bg">ctf_integer(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  21                     <li><code class="no-bg">ctf_integer_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  22                 </ul>
  23             </td>
  24             <td>
  25                 <p>Standard integer, displayed in base&nbsp;10</p>
  26                 <ul>
  27                     <li>
  28                         <code class="arg"><strong>t</strong></code> integer C type
  29                         (<code>int</code>, <code>long</code>,
  30                         <code>size_t</code>, ...)
  31                     </li>
  32                     <li><code class="arg"><strong>n</strong></code> field name</li>
  33                     <li><code class="arg"><strong>e</strong></code> argument expression</li>
  34                 </ul>
  35             </td>
  36         </tr>
  37         <tr>
  38             <td><code class="no-bg">ctf_integer_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></td>
  39             <td>
  40                 <p>Standard integer, displayed in base&nbsp;16</p>
  41                 <ul>
  42                     <li><code class="arg"><strong>t</strong></code> integer C type</li>
  43                     <li><code class="arg">n</code> field name</li>
  44                     <li><code class="arg">e</code> argument expression</li>
  45                 </ul>
  46             </td>
  47         </tr>
  48         <tr>
  49             <td><code class="no-bg">ctf_integer_network(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></td>
  50             <td>
  51                 <p>
  52                     Integer in network byte order (big endian),
  53                     displayed in base&nbsp;10
  54                 </p>
  55                 <ul>
  56                     <li><code class="arg">t</code> integer C type</li>
  57                     <li><code class="arg">n</code> field name</li>
  58                     <li><code class="arg">e</code> argument expression</li>
  59                 </ul>
  60             </td>
  61         </tr>
  62         <tr>
  63             <td><code class="no-bg">ctf_integer_network_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></td>
  64             <td>
  65                 <p>
  66                     Integer in network byte order, displayed
  67                     in base&nbsp;16</p>
  68                 <ul>
  69                     <li><code class="arg">t</code> integer C type</li>
  70                     <li><code class="arg">n</code> field name</li>
  71                     <li><code class="arg">e</code> argument expression</li>
  72                 </ul>
  73             </td>
  74         </tr>
  75         <tr>
  76             <td>
  77                 <ul>
  78                     <li><code class="no-bg">ctf_float(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  79                     <li><code class="no-bg">ctf_float_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  80                 </ul>
  81             </td>
  82             <td>
  83                 <p>Floating point number</p>
  84                 <ul>
  85                     <li>
  86                         <code class="arg">t</code> floating point number
  87                         C type (<code>float</code>, <code>double</code>)
  88                     </li>
  89                     <li><code class="arg">n</code> field name</li>
  90                     <li><code class="arg">e</code> argument expression</li>
  91                 </ul>
  92             </td>
  93         </tr>
  94         <tr>
  95             <td>
  96                 <ul>
  97                     <li><code class="no-bg">ctf_string(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  98                     <li><code class="no-bg">ctf_string_nowrite(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  99                 </ul>
 100             </td>
 101             <td>
 102                 <p>
 103                     Null-terminated string; undefined behavior if
 104                     <code class="arg">e</code> is <code>NULL</code>
 105                 </p>
 106                 <ul>
 107                     <li><code class="arg">n</code> field name</li>
 108                     <li><code class="arg">e</code> argument expression</li>
 109                 </ul>
 110             </td>
 111         </tr>
 112         <tr>
 113             <td>
 114                 <ul>
 115                     <li><code class="no-bg">ctf_array(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 116                     <li><code class="no-bg">ctf_array_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 117                 </ul>
 118             </td>
 119             <td>
 120                 <p>Statically-sized array of integers</p>
 121                 <ul>
 122                     <li><code class="arg">t</code> array element C type</li>
 123                     <li><code class="arg">n</code> field name</li>
 124                     <li><code class="arg">e</code> argument expression</li>
 125                     <li><code class="arg">s</code> number of elements</li>
 126                 </ul>
 127             </td>
 128         </tr>
 129         <tr>
 130             <td>
 131                 <ul>
 132                     <li><code class="no-bg">ctf_array_text(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 133                     <li><code class="no-bg">ctf_array_nowrite_text(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 134                 </ul>
 135             </td>
 136             <td>
 137                 <p>
 138                     Statically-sized array, printed as text; no need to be
 139                     null-terminated
 140                 </p>
 141                 <ul>
 142                     <li><code class="arg">t</code> array element C type (always <code>char</code>)</li>
 143                     <li><code class="arg">n</code> field name</li>
 144                     <li><code class="arg">e</code> argument expression</li>
 145                     <li><code class="arg">s</code> number of elements</li>
 146                 </ul>
 147             </td>
 148         </tr>
 149         <tr>
 150             <td>
 151                 <ul>
 152                     <li><code class="no-bg">ctf_sequence(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">T</span>, <span class="arg">E</span>)</code></li>
 153                     <li><code class="no-bg">ctf_sequence_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">T</span>, <span class="arg">E</span>)</code></li>
 154                 </ul>
 155             </td>
 156             <td>
 157                 <p>
 158                     Dynamically-sized array of integers; type of
 159                     <code class="arg">E</code> needs to be unsigned
 160                 </p>
 161                 <ul>
 162                     <li><code class="arg">t</code> sequence element C type</li>
 163                     <li><code class="arg">n</code> field name</li>
 164                     <li><code class="arg">e</code> argument expression</li>
 165                     <li><code class="arg">T</code> length expression C type</li>
 166                     <li><code class="arg">E</code> length expression</li>
 167                 </ul>
 168             </td>
 169         </tr>
 170         <tr>
 171             <td>
 172                 <ul>
 173                     <li><code class="no-bg">ctf_sequence_text(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">T</span>, <span class="arg">E</span>)</code></li>
 174                     <li><code class="no-bg">ctf_sequence_text_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">T</span>, <span class="arg">E</span>)</code></li>
 175                 </ul>
 176             </td>
 177             <td>
 178                 <p>
 179                     Dynamically-sized array, displayed as text; no need to
 180                     be null-terminated; undefined behavior if
 181                     <code class="arg">e</code> is <code>NULL</code></p>
 182                 <ul>
 183                     <li><code class="arg">t</code> sequence element C type (always <code>char</code>)</li>
 184                     <li><code class="arg">n</code> field name</li>
 185                     <li><code class="arg">e</code> argument expression</li>
 186                     <li><code class="arg">T</code> length expression C type</li>
 187                     <li><code class="arg">E</code> length expression</li>
 188                 </ul>
 189             </td>
 190         </tr>
 191     </tbody>
 192 </table>
 193 </div>
 194
 195 The `_nowrite` versions omit themselves from the session trace, but are
 196 otherwise identical. This means the `_nowrite` fields won't be written
 197 in the recorded trace. Their primary purpose is to make some
 198 of the event context available to the
 199 [event filters](#doc-enabling-disabling-events) without having to
 200 commit the data to sub-buffers.