| 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 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 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 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 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 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 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 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 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 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. |