contents/reference/lttng-modules/lttng-modules-tp-fields.md

   1 ---
   2 id: lttng-modules-tp-fields
   3 since: 2.7
   4 ---
   5
   6 <a name="doc-lttng-modules-tp-fast-assign"></a>
   7 <a name="doc-lttng-modules-tp-struct-entry"></a>
   8 The available macros to define tracepoint fields, which should be listed
   9 within `TP_FIELDS()` in `LTTNG_TRACEPOINT_EVENT()`, are:
  10
  11 <div class="table">
  12 <table class="func-desc">
  13     <thead>
  14         <tr>
  15             <th>Macro</th>
  16             <th>Description/arguments</th>
  17         </tr>
  18     </thead>
  19     <tbody>
  20         <tr>
  21             <td>
  22                 <ul>
  23                     <li><code class="no-bg">ctf_integer(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  24                     <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>
  25                     <li><code class="no-bg">ctf_user_integer(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  26                     <li><code class="no-bg">ctf_user_integer_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  27                 </ul>
  28             </td>
  29             <td>
  30                 <p>Standard integer, displayed in base&nbsp;10</p>
  31                 <ul>
  32                     <li>
  33                         <code class="arg"><strong>t</strong></code> integer C type
  34                         (<code>int</code>, <code>long</code>,
  35                         <code>size_t</code>, ...)
  36                     </li>
  37                     <li><code class="arg"><strong>n</strong></code> field name</li>
  38                     <li><code class="arg"><strong>e</strong></code> argument expression</li>
  39                 </ul>
  40             </td>
  41         </tr>
  42         <tr>
  43             <td>
  44                 <ul>
  45                     <li><code class="no-bg">ctf_integer_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  46                     <li><code class="no-bg">ctf_user_integer_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  47                 </ul>
  48             </td>
  49             <td>
  50                 <p>Standard integer, displayed in base&nbsp;16</p>
  51                 <ul>
  52                     <li><code class="arg"><strong>t</strong></code> integer C type</li>
  53                     <li><code class="arg">n</code> field name</li>
  54                     <li><code class="arg">e</code> argument expression</li>
  55                 </ul>
  56             </td>
  57         </tr>
  58         <tr>
  59             <td><code class="no-bg">ctf_integer_oct(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></td>
  60             <td>
  61                 <p>Standard integer, displayed in base&nbsp;8</p>
  62                 <ul>
  63                     <li><code class="arg"><strong>t</strong></code> integer C type</li>
  64                     <li><code class="arg">n</code> field name</li>
  65                     <li><code class="arg">e</code> argument expression</li>
  66                 </ul>
  67             </td>
  68         </tr>
  69         <tr>
  70             <td>
  71                 <ul>
  72                     <li><code class="no-bg">ctf_integer_network(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  73                     <li><code class="no-bg">ctf_user_integer_network(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  74                 </ul>
  75             </td>
  76             <td>
  77                 <p>
  78                     Integer in network byte order (big-endian),
  79                     displayed in base&nbsp;10
  80                 </p>
  81                 <ul>
  82                     <li><code class="arg">t</code> integer C type</li>
  83                     <li><code class="arg">n</code> field name</li>
  84                     <li><code class="arg">e</code> argument expression</li>
  85                 </ul>
  86             </td>
  87         </tr>
  88         <tr>
  89             <td>
  90                 <ul>
  91                     <li><code class="no-bg">ctf_integer_network_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  92                     <li><code class="no-bg">ctf_user_integer_network_hex(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
  93                 </ul>
  94             </td>
  95             <td>
  96                 <p>
  97                     Integer in network byte order, displayed
  98                     in base&nbsp;16</p>
  99                 <ul>
 100                     <li><code class="arg">t</code> integer C type</li>
 101                     <li><code class="arg">n</code> field name</li>
 102                     <li><code class="arg">e</code> argument expression</li>
 103                 </ul>
 104             </td>
 105         </tr>
 106         <tr>
 107             <td>
 108                 <ul>
 109                     <li><code class="no-bg">ctf_float(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 110                     <li><code class="no-bg">ctf_user_float(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 111                     <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>
 112                     <li><code class="no-bg">ctf_user_float_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 113                 </ul>
 114             </td>
 115             <td>
 116                 <p>Floating point number</p>
 117                 <ul>
 118                     <li>
 119                         <code class="arg">t</code> floating point number
 120                         C type (<code>float</code>, <code>double</code>)
 121                     </li>
 122                     <li><code class="arg">n</code> field name</li>
 123                     <li><code class="arg">e</code> argument expression</li>
 124                 </ul>
 125             </td>
 126         </tr>
 127         <tr>
 128             <td>
 129                 <ul>
 130                     <li><code class="no-bg">ctf_string(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 131                     <li><code class="no-bg">ctf_user_string(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 132                     <li><code class="no-bg">ctf_string_nowrite(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 133                     <li><code class="no-bg">ctf_user_string_nowrite(<span class="arg">n</span>, <span class="arg">e</span>)</code></li>
 134                 </ul>
 135             </td>
 136             <td>
 137                 <p>
 138                     Null-terminated string; undefined behavior if
 139                     <code class="arg">e</code> is <code>NULL</code>
 140                 </p>
 141                 <ul>
 142                     <li><code class="arg">n</code> field name</li>
 143                     <li><code class="arg">e</code> argument expression</li>
 144                 </ul>
 145             </td>
 146         </tr>
 147         <tr>
 148             <td>
 149                 <ul>
 150                     <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>
 151                     <li><code class="no-bg">ctf_user_array(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 152                     <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>
 153                     <li><code class="no-bg">ctf_user_array_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 154                 </ul>
 155             </td>
 156             <td>
 157                 <p>
 158                     Statically-sized array of integers, displayed in
 159                     base&nbsp;10
 160                 </p>
 161                 <ul>
 162                     <li><code class="arg">t</code> array 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">s</code> number of elements</li>
 166                 </ul>
 167             </td>
 168         </tr>
 169         <tr>
 170             <td>
 171                 <ul>
 172                     <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>
 173                     <li><code class="no-bg">ctf_user_array_text(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 174                     <li><code class="no-bg">ctf_array_text_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 175                     <li><code class="no-bg">ctf_user_array_text_nowrite(<span class="arg">t</span>, <span class="arg">n</span>, <span class="arg">e</span>, <span class="arg">s</span>)</code></li>
 176                 </ul>
 177             </td>
 178             <td>
 179                 <p>
 180                     Statically-sized array, printed as text; no need to
 181                     be null-terminated
 182                 </p>
 183                 <ul>
 184                     <li><code class="arg">t</code> array element C type (always <code>char</code>)</li>
 185                     <li><code class="arg">n</code> field name</li>
 186                     <li><code class="arg">e</code> argument expression</li>
 187                     <li><code class="arg">s</code> number of elements</li>
 188                 </ul>
 189             </td>
 190         </tr>
 191         <tr>
 192             <td>
 193                 <ul>
 194                     <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>
 195                     <li><code class="no-bg">ctf_user_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>
 196                     <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>
 197                     <li><code class="no-bg">ctf_user_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>
 198                 </ul>
 199             </td>
 200             <td>
 201                 <p>
 202                     Dynamically-sized array of integers, displayed in
 203                     base&nbsp;10; type of
 204                     <code class="arg">E</code> needs to be unsigned
 205                 </p>
 206                 <ul>
 207                     <li><code class="arg">t</code> sequence element C type</li>
 208                     <li><code class="arg">n</code> field name</li>
 209                     <li><code class="arg">e</code> argument expression</li>
 210                     <li><code class="arg">T</code> length expression C type</li>
 211                     <li><code class="arg">E</code> length expression</li>
 212                 </ul>
 213             </td>
 214         </tr>
 215         <tr>
 216             <td>
 217                 <ul>
 218                     <li><code class="no-bg">ctf_sequence_hex(<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>
 219                 </ul>
 220             </td>
 221             <td>
 222                 <p>
 223                     Dynamically-sized array of integers, displayed in
 224                     base&nbsp;16; type of
 225                     <code class="arg">E</code> needs to be unsigned
 226                 </p>
 227                 <ul>
 228                     <li><code class="arg">t</code> sequence element C type</li>
 229                     <li><code class="arg">n</code> field name</li>
 230                     <li><code class="arg">e</code> argument expression</li>
 231                     <li><code class="arg">T</code> length expression C type</li>
 232                     <li><code class="arg">E</code> length expression</li>
 233                 </ul>
 234             </td>
 235         </tr>
 236         <tr>
 237             <td>
 238                 <ul>
 239                     <li><code class="no-bg">ctf_sequence_network(<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>
 240                 </ul>
 241             </td>
 242             <td>
 243                 <p>
 244                     Dynamically-sized array of integers in network byte
 245                     order (big endian), displayed in base&nbsp;10;
 246                     type of
 247
 248
 249
 250                     <code class="arg">E</code> needs to be unsigned
 251                 </p>
 252                 <ul>
 253                     <li><code class="arg">t</code> sequence element C type</li>
 254                     <li><code class="arg">n</code> field name</li>
 255                     <li><code class="arg">e</code> argument expression</li>
 256                     <li><code class="arg">T</code> length expression C type</li>
 257                     <li><code class="arg">E</code> length expression</li>
 258                 </ul>
 259             </td>
 260         </tr>
 261         <tr>
 262             <td>
 263                 <ul>
 264                     <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>
 265                     <li><code class="no-bg">ctf_user_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>
 266                     <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>
 267                     <li><code class="no-bg">ctf_user_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>
 268                 </ul>
 269             </td>
 270             <td>
 271                 <p>
 272                     Dynamically-sized array, displayed as text; no need to
 273                     be null-terminated; undefined behavior if
 274                     <code class="arg">e</code> is <code>NULL</code></p>
 275                 <ul>
 276                     <li><code class="arg">t</code> sequence element C type (always <code>char</code>)</li>
 277                     <li><code class="arg">n</code> field name</li>
 278                     <li><code class="arg">e</code> argument expression</li>
 279                     <li><code class="arg">T</code> length expression C type</li>
 280                     <li><code class="arg">E</code> length expression</li>
 281                 </ul>
 282             </td>
 283         </tr>
 284     </tbody>
 285 </table>
 286 </div>
 287
 288 The `_user` versions must be used when the argument expression, `e`, is
 289 a user space address. In the cases of `ctf_user_integer*()` and
 290 `ctf_user_float*()`, `&e` must be a user space address, thus `e` must
 291 be addressable.
 292
 293 The `_nowrite` versions omit themselves from the session trace, but are
 294 otherwise identical. This means the `_nowrite` fields won't be written
 295 in the recorded trace. Their primary purpose is to make some
 296 of the event context available to the
 297 [event filters](#doc-enabling-disabling-events) without having to
 298 commit the data to sub-buffers.