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

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