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

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