Commit | Line | Data |
---|---|---|
3b033380 MCC |
1 | ========================================= |
2 | How to get printk format specifiers right | |
3 | ========================================= | |
4 | ||
5 | :Author: Randy Dunlap <rdunlap@infradead.org> | |
6 | :Author: Andrew Murray <amurray@mpc-data.co.uk> | |
7 | ||
3b033380 MCC |
8 | Integer types |
9 | ============= | |
10 | ||
11 | :: | |
12 | ||
13 | If variable is of Type, use printk format specifier: | |
14 | ------------------------------------------------------------ | |
b67ad18b RD |
15 | int %d or %x |
16 | unsigned int %u or %x | |
17 | long %ld or %lx | |
18 | unsigned long %lu or %lx | |
19 | long long %lld or %llx | |
20 | unsigned long long %llu or %llx | |
21 | size_t %zu or %zx | |
22 | ssize_t %zd or %zx | |
e8a7ba5f GU |
23 | s32 %d or %x |
24 | u32 %u or %x | |
25 | s64 %lld or %llx | |
26 | u64 %llu or %llx | |
27 | ||
3b033380 MCC |
28 | If <type> is dependent on a config option for its size (e.g., ``sector_t``, |
29 | ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``), | |
30 | use a format specifier of its largest possible type and explicitly cast to it. | |
31 | ||
32 | Example:: | |
e8a7ba5f GU |
33 | |
34 | printk("test: sector number/total blocks: %llu/%llu\n", | |
35 | (unsigned long long)sector, (unsigned long long)blockcount); | |
36 | ||
3b033380 | 37 | Reminder: ``sizeof()`` result is of type ``size_t``. |
e8a7ba5f | 38 | |
3b033380 MCC |
39 | The kernel's printf does not support ``%n``. For obvious reasons, floating |
40 | point formats (``%e, %f, %g, %a``) are also not recognized. Use of any | |
d7ec9a05 RV |
41 | unsupported specifier or length qualifier results in a WARN and early |
42 | return from vsnprintf. | |
b67ad18b | 43 | |
04c55715 AM |
44 | Raw pointer value SHOULD be printed with %p. The kernel supports |
45 | the following extended format specifiers for pointer types: | |
46 | ||
ad67b74d TH |
47 | Pointer Types |
48 | ============= | |
49 | ||
50 | Pointers printed without a specifier extension (i.e unadorned %p) are | |
51 | hashed to give a unique identifier without leaking kernel addresses to user | |
7b1924a1 TH |
52 | space. On 64 bit machines the first 32 bits are zeroed. If you _really_ |
53 | want the address see %px below. | |
ad67b74d TH |
54 | |
55 | :: | |
56 | ||
57 | %p abcdef12 or 00000000abcdef12 | |
58 | ||
3b033380 MCC |
59 | Symbols/Function Pointers |
60 | ========================= | |
61 | ||
62 | :: | |
04c55715 AM |
63 | |
64 | %pF versatile_init+0x0/0x110 | |
65 | %pf versatile_init | |
66 | %pS versatile_init+0x0/0x110 | |
b0d33c2b JP |
67 | %pSR versatile_init+0x9/0x110 |
68 | (with __builtin_extract_return_addr() translation) | |
04c55715 AM |
69 | %ps versatile_init |
70 | %pB prev_fn_of_versatile_init+0x88/0x88 | |
71 | ||
d6957f33 HD |
72 | The ``F`` and ``f`` specifiers are for printing function pointers, |
73 | for example, f->func, &gettimeofday. They have the same result as | |
74 | ``S`` and ``s`` specifiers. But they do an extra conversion on | |
75 | ia64, ppc64 and parisc64 architectures where the function pointers | |
76 | are actually function descriptors. | |
77 | ||
78 | The ``S`` and ``s`` specifiers can be used for printing symbols | |
79 | from direct addresses, for example, __builtin_return_address(0), | |
80 | (void *)regs->ip. They result in the symbol name with (``S``) or | |
81 | without (``s``) offsets. If KALLSYMS are disabled then the symbol | |
82 | address is printed instead. | |
3b033380 MCC |
83 | |
84 | The ``B`` specifier results in the symbol name with offsets and should be | |
85 | used when printing stack backtraces. The specifier takes into | |
86 | consideration the effect of compiler optimisations which may occur | |
87 | when tail-call``s are used and marked with the noreturn GCC attribute. | |
04c55715 | 88 | |
fd46cd55 HD |
89 | Examples:: |
90 | ||
91 | printk("Going to call: %pF\n", gettimeofday); | |
92 | printk("Going to call: %pF\n", p->func); | |
93 | printk("%s: called from %pS\n", __func__, (void *)_RET_IP_); | |
94 | printk("%s: called from %pS\n", __func__, | |
95 | (void *)__builtin_return_address(0)); | |
96 | printk("Faulted at %pS\n", (void *)regs->ip); | |
97 | printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack); | |
98 | ||
3b033380 MCC |
99 | Kernel Pointers |
100 | =============== | |
04c55715 | 101 | |
3b033380 | 102 | :: |
04c55715 | 103 | |
553d8e8b | 104 | %pK 01234567 or 0123456789abcdef |
04c55715 | 105 | |
3b033380 MCC |
106 | For printing kernel pointers which should be hidden from unprivileged |
107 | users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see | |
108 | Documentation/sysctl/kernel.txt for more details. | |
109 | ||
7b1924a1 TH |
110 | Unmodified Addresses |
111 | ==================== | |
112 | ||
113 | :: | |
114 | ||
115 | %px 01234567 or 0123456789abcdef | |
116 | ||
117 | For printing pointers when you _really_ want to print the address. Please | |
118 | consider whether or not you are leaking sensitive information about the | |
119 | Kernel layout in memory before printing pointers with %px. %px is | |
120 | functionally equivalent to %lx. %px is preferred to %lx because it is more | |
121 | uniquely grep'able. If, in the future, we need to modify the way the Kernel | |
122 | handles printing pointers it will be nice to be able to find the call | |
123 | sites. | |
124 | ||
3b033380 MCC |
125 | Struct Resources |
126 | ================ | |
04c55715 | 127 | |
3b033380 | 128 | :: |
04c55715 AM |
129 | |
130 | %pr [mem 0x60000000-0x6fffffff flags 0x2200] or | |
131 | [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] | |
132 | %pR [mem 0x60000000-0x6fffffff pref] or | |
133 | [mem 0x0000000060000000-0x000000006fffffff pref] | |
134 | ||
3b033380 MCC |
135 | For printing struct resources. The ``R`` and ``r`` specifiers result in a |
136 | printed resource with (``R``) or without (``r``) a decoded flags member. | |
137 | Passed by reference. | |
138 | ||
139 | Physical addresses types ``phys_addr_t`` | |
140 | ======================================== | |
04c55715 | 141 | |
3b033380 | 142 | :: |
7d799210 | 143 | |
aaf07621 | 144 | %pa[p] 0x01234567 or 0x0123456789abcdef |
7d799210 | 145 | |
3b033380 MCC |
146 | For printing a ``phys_addr_t`` type (and its derivatives, such as |
147 | ``resource_size_t``) which can vary based on build options, regardless of | |
148 | the width of the CPU data path. Passed by reference. | |
7d799210 | 149 | |
3b033380 MCC |
150 | DMA addresses types ``dma_addr_t`` |
151 | ================================== | |
152 | ||
153 | :: | |
aaf07621 JP |
154 | |
155 | %pad 0x01234567 or 0x0123456789abcdef | |
156 | ||
3b033380 MCC |
157 | For printing a ``dma_addr_t`` type which can vary based on build options, |
158 | regardless of the width of the CPU data path. Passed by reference. | |
159 | ||
160 | Raw buffer as an escaped string | |
161 | =============================== | |
aaf07621 | 162 | |
3b033380 | 163 | :: |
71dca95d AS |
164 | |
165 | %*pE[achnops] | |
166 | ||
3b033380 | 167 | For printing raw buffer as an escaped string. For the following buffer:: |
71dca95d AS |
168 | |
169 | 1b 62 20 5c 43 07 22 90 0d 5d | |
170 | ||
3b033380 MCC |
171 | few examples show how the conversion would be done (the result string |
172 | without surrounding quotes):: | |
71dca95d AS |
173 | |
174 | %*pE "\eb \C\a"\220\r]" | |
175 | %*pEhp "\x1bb \C\x07"\x90\x0d]" | |
176 | %*pEa "\e\142\040\\\103\a\042\220\r\135" | |
177 | ||
3b033380 MCC |
178 | The conversion rules are applied according to an optional combination |
179 | of flags (see :c:func:`string_escape_mem` kernel documentation for the | |
180 | details): | |
181 | ||
182 | - ``a`` - ESCAPE_ANY | |
183 | - ``c`` - ESCAPE_SPECIAL | |
184 | - ``h`` - ESCAPE_HEX | |
185 | - ``n`` - ESCAPE_NULL | |
186 | - ``o`` - ESCAPE_OCTAL | |
187 | - ``p`` - ESCAPE_NP | |
188 | - ``s`` - ESCAPE_SPACE | |
71dca95d | 189 | |
3b033380 | 190 | By default ESCAPE_ANY_NP is used. |
71dca95d | 191 | |
3b033380 MCC |
192 | ESCAPE_ANY_NP is the sane choice for many cases, in particularly for |
193 | printing SSIDs. | |
71dca95d | 194 | |
3b033380 MCC |
195 | If field width is omitted the 1 byte only will be escaped. |
196 | ||
197 | Raw buffer as a hex string | |
198 | ========================== | |
199 | ||
200 | :: | |
5e4ee7b1 | 201 | |
31550a16 AS |
202 | %*ph 00 01 02 ... 3f |
203 | %*phC 00:01:02: ... :3f | |
204 | %*phD 00-01-02- ... -3f | |
205 | %*phN 000102 ... 3f | |
206 | ||
3b033380 MCC |
207 | For printing a small buffers (up to 64 bytes long) as a hex string with |
208 | certain separator. For the larger buffers consider to use | |
209 | :c:func:`print_hex_dump`. | |
210 | ||
211 | MAC/FDDI addresses | |
212 | ================== | |
31550a16 | 213 | |
3b033380 | 214 | :: |
04c55715 AM |
215 | |
216 | %pM 00:01:02:03:04:05 | |
76597ff9 | 217 | %pMR 05:04:03:02:01:00 |
04c55715 AM |
218 | %pMF 00-01-02-03-04-05 |
219 | %pm 000102030405 | |
7c59154e | 220 | %pmR 050403020100 |
04c55715 | 221 | |
3b033380 MCC |
222 | For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` |
223 | specifiers result in a printed address with (``M``) or without (``m``) byte | |
224 | separators. The default byte separator is the colon (``:``). | |
04c55715 | 225 | |
3b033380 MCC |
226 | Where FDDI addresses are concerned the ``F`` specifier can be used after |
227 | the ``M`` specifier to use dash (``-``) separators instead of the default | |
228 | separator. | |
04c55715 | 229 | |
3b033380 MCC |
230 | For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` |
231 | specifier to use reversed byte order suitable for visual interpretation | |
232 | of Bluetooth addresses which are in the little endian order. | |
76597ff9 | 233 | |
3b033380 MCC |
234 | Passed by reference. |
235 | ||
236 | IPv4 addresses | |
237 | ============== | |
7330660e | 238 | |
3b033380 | 239 | :: |
04c55715 AM |
240 | |
241 | %pI4 1.2.3.4 | |
242 | %pi4 001.002.003.004 | |
8ecada16 | 243 | %p[Ii]4[hnbl] |
04c55715 | 244 | |
3b033380 MCC |
245 | For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` |
246 | specifiers result in a printed address with (``i4``) or without (``I4``) | |
247 | leading zeros. | |
04c55715 | 248 | |
3b033380 MCC |
249 | The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify |
250 | host, network, big or little endian order addresses respectively. Where | |
251 | no specifier is provided the default network/big endian order is used. | |
04c55715 | 252 | |
3b033380 | 253 | Passed by reference. |
7330660e | 254 | |
3b033380 MCC |
255 | IPv6 addresses |
256 | ============== | |
257 | ||
258 | :: | |
04c55715 AM |
259 | |
260 | %pI6 0001:0002:0003:0004:0005:0006:0007:0008 | |
261 | %pi6 00010002000300040005000600070008 | |
262 | %pI6c 1:2:3:4:5:6:7:8 | |
263 | ||
3b033380 MCC |
264 | For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` |
265 | specifiers result in a printed address with (``I6``) or without (``i6``) | |
266 | colon-separators. Leading zeros are always used. | |
04c55715 | 267 | |
3b033380 MCC |
268 | The additional ``c`` specifier can be used with the ``I`` specifier to |
269 | print a compressed IPv6 address as described by | |
270 | http://tools.ietf.org/html/rfc5952 | |
04c55715 | 271 | |
3b033380 | 272 | Passed by reference. |
7330660e | 273 | |
3b033380 MCC |
274 | IPv4/IPv6 addresses (generic, with port, flowinfo, scope) |
275 | ========================================================= | |
276 | ||
277 | :: | |
10679643 DB |
278 | |
279 | %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 | |
280 | %piS 001.002.003.004 or 00010002000300040005000600070008 | |
281 | %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 | |
282 | %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 | |
283 | %p[Ii]S[pfschnbl] | |
284 | ||
3b033380 MCC |
285 | For printing an IP address without the need to distinguish whether it``s |
286 | of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``, | |
287 | specified through ``IS`` or ``iS``, can be passed to this format specifier. | |
10679643 | 288 | |
3b033380 MCC |
289 | The additional ``p``, ``f``, and ``s`` specifiers are used to specify port |
290 | (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, | |
291 | flowinfo a ``/`` and scope a ``%``, each followed by the actual value. | |
10679643 | 292 | |
3b033380 MCC |
293 | In case of an IPv6 address the compressed IPv6 address as described by |
294 | http://tools.ietf.org/html/rfc5952 is being used if the additional | |
295 | specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in | |
296 | case of additional specifiers ``p``, ``f`` or ``s`` as suggested by | |
297 | https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 | |
10679643 | 298 | |
3b033380 MCC |
299 | In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` |
300 | specifiers can be used as well and are ignored in case of an IPv6 | |
301 | address. | |
10679643 | 302 | |
3b033380 | 303 | Passed by reference. |
7330660e | 304 | |
3b033380 | 305 | Further examples:: |
10679643 DB |
306 | |
307 | %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 | |
308 | %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 | |
309 | %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 | |
310 | ||
3b033380 MCC |
311 | UUID/GUID addresses |
312 | =================== | |
313 | ||
314 | :: | |
04c55715 AM |
315 | |
316 | %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f | |
317 | %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F | |
318 | %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f | |
319 | %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F | |
320 | ||
3b033380 MCC |
321 | For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L', |
322 | 'b' and 'B' specifiers are used to specify a little endian order in | |
323 | lower ('l') or upper case ('L') hex characters - and big endian order | |
324 | in lower ('b') or upper case ('B') hex characters. | |
04c55715 | 325 | |
3b033380 MCC |
326 | Where no additional specifiers are used the default big endian |
327 | order with lower case hex characters will be printed. | |
04c55715 | 328 | |
3b033380 MCC |
329 | Passed by reference. |
330 | ||
331 | dentry names | |
332 | ============ | |
7330660e | 333 | |
3b033380 | 334 | :: |
5e4ee7b1 | 335 | |
4b6ccca7 AV |
336 | %pd{,2,3,4} |
337 | %pD{,2,3,4} | |
338 | ||
3b033380 MCC |
339 | For printing dentry name; if we race with :c:func:`d_move`, the name might be |
340 | a mix of old and new ones, but it won't oops. ``%pd`` dentry is a safer | |
341 | equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints | |
342 | ``n`` last components. ``%pD`` does the same thing for struct file. | |
4b6ccca7 | 343 | |
3b033380 | 344 | Passed by reference. |
7330660e | 345 | |
3b033380 MCC |
346 | block_device names |
347 | ================== | |
348 | ||
349 | :: | |
1031bc58 DM |
350 | |
351 | %pg sda, sda1 or loop0p1 | |
352 | ||
3b033380 MCC |
353 | For printing name of block_device pointers. |
354 | ||
355 | struct va_format | |
356 | ================ | |
1031bc58 | 357 | |
3b033380 | 358 | :: |
04c55715 AM |
359 | |
360 | %pV | |
361 | ||
3b033380 MCC |
362 | For printing struct va_format structures. These contain a format string |
363 | and va_list as follows:: | |
04c55715 AM |
364 | |
365 | struct va_format { | |
366 | const char *fmt; | |
367 | va_list *va; | |
368 | }; | |
369 | ||
3b033380 | 370 | Implements a "recursive vsnprintf". |
5e4ee7b1 | 371 | |
3b033380 MCC |
372 | Do not use this feature without some mechanism to verify the |
373 | correctness of the format string and va_list arguments. | |
b67ad18b | 374 | |
3b033380 MCC |
375 | Passed by reference. |
376 | ||
377 | kobjects | |
378 | ======== | |
379 | ||
380 | :: | |
7330660e | 381 | |
ce4fecf1 PA |
382 | %pO |
383 | ||
384 | Base specifier for kobject based structs. Must be followed with | |
385 | character for specific type of kobject as listed below: | |
386 | ||
387 | Device tree nodes: | |
388 | ||
389 | %pOF[fnpPcCF] | |
390 | ||
391 | For printing device tree nodes. The optional arguments are: | |
392 | f device node full_name | |
393 | n device node name | |
394 | p device node phandle | |
395 | P device node path spec (name + @unit) | |
396 | F device node flags | |
397 | c major compatible string | |
398 | C full compatible string | |
399 | Without any arguments prints full_name (same as %pOFf) | |
400 | The separator when using multiple arguments is ':' | |
401 | ||
402 | Examples: | |
403 | ||
404 | %pOF /foo/bar@0 - Node full name | |
405 | %pOFf /foo/bar@0 - Same as above | |
406 | %pOFfp /foo/bar@0:10 - Node full name + phandle | |
407 | %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + | |
408 | major compatible string + | |
409 | node flags | |
410 | D - dynamic | |
411 | d - detached | |
412 | P - Populated | |
413 | B - Populated bus | |
414 | ||
415 | Passed by reference. | |
416 | ||
3b033380 MCC |
417 | |
418 | struct clk | |
419 | ========== | |
420 | ||
421 | :: | |
900cca29 GU |
422 | |
423 | %pC pll1 | |
424 | %pCn pll1 | |
425 | %pCr 1560000000 | |
426 | ||
3b033380 MCC |
427 | For printing struct clk structures. ``%pC`` and ``%pCn`` print the name |
428 | (Common Clock Framework) or address (legacy clock framework) of the | |
429 | structure; ``%pCr`` prints the current clock rate. | |
900cca29 | 430 | |
3b033380 | 431 | Passed by reference. |
900cca29 | 432 | |
3b033380 MCC |
433 | bitmap and its derivatives such as cpumask and nodemask |
434 | ======================================================= | |
435 | ||
436 | :: | |
d0724961 WL |
437 | |
438 | %*pb 0779 | |
439 | %*pbl 0,3-6,8-10 | |
440 | ||
3b033380 MCC |
441 | For printing bitmap and its derivatives such as cpumask and nodemask, |
442 | ``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl`` | |
443 | output the bitmap as range list with field width as the number of bits. | |
d0724961 | 444 | |
3b033380 MCC |
445 | Passed by reference. |
446 | ||
447 | Flags bitfields such as page flags, gfp_flags | |
448 | ============================================= | |
b67ad18b | 449 | |
3b033380 | 450 | :: |
edf14cdb VB |
451 | |
452 | %pGp referenced|uptodate|lru|active|private | |
453 | %pGg GFP_USER|GFP_DMA32|GFP_NOWARN | |
454 | %pGv read|exec|mayread|maywrite|mayexec|denywrite | |
455 | ||
3b033380 MCC |
456 | For printing flags bitfields as a collection of symbolic constants that |
457 | would construct the value. The type of flags is given by the third | |
458 | character. Currently supported are [p]age flags, [v]ma_flags (both | |
459 | expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag | |
460 | names and print order depends on the particular type. | |
edf14cdb | 461 | |
3b033380 MCC |
462 | Note that this format should not be used directly in :c:func:`TP_printk()` part |
463 | of a tracepoint. Instead, use the ``show_*_flags()`` functions from | |
464 | <trace/events/mmflags.h>. | |
edf14cdb | 465 | |
3b033380 MCC |
466 | Passed by reference. |
467 | ||
468 | Network device features | |
469 | ======================= | |
edf14cdb | 470 | |
3b033380 | 471 | :: |
5e4ee7b1 MK |
472 | |
473 | %pNF 0x000000000000c000 | |
474 | ||
3b033380 | 475 | For printing netdev_features_t. |
5e4ee7b1 | 476 | |
3b033380 | 477 | Passed by reference. |
5e4ee7b1 | 478 | |
3b033380 | 479 | If you add other ``%p`` extensions, please extend lib/test_printf.c with |
d7ec9a05 | 480 | one or more test cases, if at all feasible. |
5e4ee7b1 | 481 | |
5e4ee7b1 | 482 | |
b67ad18b | 483 | Thank you for your cooperation and attention. |