1 =========================================
2 How to get printk format specifiers right
3 =========================================
4
5 .. _printk-specifiers:
6
7 :Author: Randy Dunlap <rdunlap@infradead.org>
8 :Author: Andrew Murray <amurray@mpc-data.co.uk>
9
10
11 Integer types
12 =============
13
14 ::
15
16 If variable is of Type, use printk format specifier:
17 ------------------------------------------------------------
18 signed char %d or %hhx
19 unsigned char %u or %x
20 char %u or %x
21 short int %d or %hx
22 unsigned short int %u or %x
23 int %d or %x
24 unsigned int %u or %x
25 long %ld or %lx
26 unsigned long %lu or %lx
27 long long %lld or %llx
28 unsigned long long %llu or %llx
29 size_t %zu or %zx
30 ssize_t %zd or %zx
31 s8 %d or %hhx
32 u8 %u or %x
33 s16 %d or %hx
34 u16 %u or %x
35 s32 %d or %x
36 u32 %u or %x
37 s64 %lld or %llx
38 u64 %llu or %llx
39
40
41 If <type> is architecture-dependent for its size (e.g., cycles_t, tcflag_t) or
42 is dependent on a config option for its size (e.g., blk_status_t), use a format
43 specifier of its largest possible type and explicitly cast to it.
44
45 Example::
46
47 printk("test: latency: %llu cycles\n", (unsigned long long)time);
48
49 Reminder: sizeof() returns type size_t.
50
51 The kernel's printf does not support %n. Floating point formats (%e, %f,
52 %g, %a) are also not recognized, for obvious reasons. Use of any
53 unsupported specifier or length qualifier results in a WARN and early
54 return from vsnprintf().
55
56 Pointer types
57 =============
58
59 A raw pointer value may be printed with %p which will hash the address
60 before printing. The kernel also supports extended specifiers for printing
61 pointers of different types.
62
63 Some of the extended specifiers print the data on the given address instead
64 of printing the address itself. In this case, the following error messages
65 might be printed instead of the unreachable information::
66
67 (null) data on plain NULL address
68 (efault) data on invalid address
69 (einval) invalid data on a valid address
70
71 Plain Pointers
72 --------------
73
74 ::
75
76 %p abcdef12 or 00000000abcdef12
77
78 Pointers printed without a specifier extension (i.e unadorned %p) are
79 hashed to prevent leaking information about the kernel memory layout. This
80 has the added benefit of providing a unique identifier. On 64-bit machines
81 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
82 gathers enough entropy.
83
84 When possible, use specialised modifiers such as %pS or %pB (described below)
85 to avoid the need of providing an unhashed address that has to be interpreted
86 post-hoc. If not possible, and the aim of printing the address is to provide
87 more information for debugging, use %p and boot the kernel with the
88 ``no_hash_pointers`` parameter during debugging, which will print all %p
89 addresses unmodified. If you *really* always want the unmodified address, see
90 %px below.
91
92 If (and only if) you are printing addresses as a content of a virtual file in
93 e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a
94 userspace process, use the %pK modifier described below instead of %p or %px.
95
96 Error Pointers
97 --------------
98
99 ::
100
101 %pe -ENOSPC
102
103 For printing error pointers (i.e. a pointer for which IS_ERR() is true)
104 as a symbolic error name. Error values for which no symbolic name is
105 known are printed in decimal, while a non-ERR_PTR passed as the
106 argument to %pe gets treated as ordinary %p.
107
108 Symbols/Function Pointers
109 -------------------------
110
111 ::
112
113 %pS versatile_init+0x0/0x110
114 %ps versatile_init
115 %pSR versatile_init+0x9/0x110
116 (with __builtin_extract_return_addr() translation)
117 %pB prev_fn_of_versatile_init+0x88/0x88
118
119
120 The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic
121 format. They result in the symbol name with (S) or without (s)
122 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
123
124 The ``B`` specifier results in the symbol name with offsets and should be
125 used when printing stack backtraces. The specifier takes into
126 consideration the effect of compiler optimisations which may occur
127 when tail-calls are used and marked with the noreturn GCC attribute.
128
129 If the pointer is within a module, the module name and optionally build ID is
130 printed after the symbol name with an extra ``b`` appended to the end of the
131 specifier.
132
133 ::
134
135 %pS versatile_init+0x0/0x110 [module_name]
136 %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]
137 %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]
138 (with __builtin_extract_return_addr() translation)
139 %pBb prev_fn_of_versatile_init+0x88/0x88 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]
140
141 Probed Pointers from BPF / tracing
142 ----------------------------------
143
144 ::
145
146 %pks kernel string
147 %pus user string
148
149 The ``k`` and ``u`` specifiers are used for printing prior probed memory from
150 either kernel memory (k) or user memory (u). The subsequent ``s`` specifier
151 results in printing a string. For direct use in regular vsnprintf() the (k)
152 and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(),
153 for example, it reads the memory it is pointing to without faulting.
154
155 Kernel Pointers
156 ---------------
157
158 ::
159
160 %pK 01234567 or 0123456789abcdef
161
162 For printing kernel pointers which should be hidden from unprivileged
163 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
164 Documentation/admin-guide/sysctl/kernel.rst for more details.
165
166 This modifier is *only* intended when producing content of a file read by
167 userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the
168 section about %p above for discussion about how to manage hashing pointers
169 in printk().
170
171 Unmodified Addresses
172 --------------------
173
174 ::
175
176 %px 01234567 or 0123456789abcdef
177
178 For printing pointers when you *really* want to print the address. Please
179 consider whether or not you are leaking sensitive information about the
180 kernel memory layout before printing pointers with %px. %px is functionally
181 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
182 grep'able. If in the future we need to modify the way the kernel handles
183 printing pointers we will be better equipped to find the call sites.
184
185 Before using %px, consider if using %p is sufficient together with enabling the
186 ``no_hash_pointers`` kernel parameter during debugging sessions (see the %p
187 description above). One valid scenario for %px might be printing information
188 immediately before a panic, which prevents any sensitive information to be
189 exploited anyway, and with %px there would be no need to reproduce the panic
190 with no_hash_pointers.
191
192 Pointer Differences
193 -------------------
194
195 ::
196
197 %td 2560
198 %tx a00
199
200 For printing the pointer differences, use the %t modifier for ptrdiff_t.
201
202 Example::
203
204 printk("test: difference between pointers: %td\n", ptr2 - ptr1);
205
206 Struct Resources
207 ----------------
208
209 ::
210
211 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or
212 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
213 %pR [mem 0x60000000-0x6fffffff pref] or
214 [mem 0x0000000060000000-0x000000006fffffff pref]
215
216 For printing struct resources. The ``R`` and ``r`` specifiers result in a
217 printed resource with (R) or without (r) a decoded flags member.
218
219 Passed by reference.
220
221 Physical address types phys_addr_t
222 ----------------------------------
223
224 ::
225
226 %pa[p] 0x01234567 or 0x0123456789abcdef
227
228 For printing a phys_addr_t type (and its derivatives, such as
229 resource_size_t) which can vary based on build options, regardless of the
230 width of the CPU data path.
231
232 Passed by reference.
233
234 DMA address types dma_addr_t
235 ----------------------------
236
237 ::
238
239 %pad 0x01234567 or 0x0123456789abcdef
240
241 For printing a dma_addr_t type which can vary based on build options,
242 regardless of the width of the CPU data path.
243
244 Passed by reference.
245
246 Raw buffer as an escaped string
247 -------------------------------
248
249 ::
250
251 %*pE[achnops]
252
253 For printing raw buffer as an escaped string. For the following buffer::
254
255 1b 62 20 5c 43 07 22 90 0d 5d
256
257 A few examples show how the conversion would be done (excluding surrounding
258 quotes)::
259
260 %*pE "\eb \C\a"\220\r]"
261 %*pEhp "\x1bb \C\x07"\x90\x0d]"
262 %*pEa "\e\142\040\\\103\a\042\220\r\135"
263
264 The conversion rules are applied according to an optional combination
265 of flags (see :c:func:`string_escape_mem` kernel documentation for the
266 details):
267
268 - a - ESCAPE_ANY
269 - c - ESCAPE_SPECIAL
270 - h - ESCAPE_HEX
271 - n - ESCAPE_NULL
272 - o - ESCAPE_OCTAL
273 - p - ESCAPE_NP
274 - s - ESCAPE_SPACE
275
276 By default ESCAPE_ANY_NP is used.
277
278 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
279 printing SSIDs.
280
281 If field width is omitted then 1 byte only will be escaped.
282
283 Raw buffer as a hex string
284 --------------------------
285
286 ::
287
288 %*ph 00 01 02 ... 3f
289 %*phC 00:01:02: ... :3f
290 %*phD 00-01-02- ... -3f
291 %*phN 000102 ... 3f
292
293 For printing small buffers (up to 64 bytes long) as a hex string with a
294 certain separator. For larger buffers consider using
295 :c:func:`print_hex_dump`.
296
297 MAC/FDDI addresses
298 ------------------
299
300 ::
301
302 %pM 00:01:02:03:04:05
303 %pMR 05:04:03:02:01:00
304 %pMF 00-01-02-03-04-05
305 %pm 000102030405
306 %pmR 050403020100
307
308 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
309 specifiers result in a printed address with (M) or without (m) byte
310 separators. The default byte separator is the colon (:).
311
312 Where FDDI addresses are concerned the ``F`` specifier can be used after
313 the ``M`` specifier to use dash (-) separators instead of the default
314 separator.
315
316 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
317 specifier to use reversed byte order suitable for visual interpretation
318 of Bluetooth addresses which are in the little endian order.
319
320 Passed by reference.
321
322 IPv4 addresses
323 --------------
324
325 ::
326
327 %pI4 1.2.3.4
328 %pi4 001.002.003.004
329 %p[Ii]4[hnbl]
330
331 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
332 specifiers result in a printed address with (i4) or without (I4) leading
333 zeros.
334
335 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
336 host, network, big or little endian order addresses respectively. Where
337 no specifier is provided the default network/big endian order is used.
338
339 Passed by reference.
340
341 IPv6 addresses
342 --------------
343
344 ::
345
346 %pI6 0001:0002:0003:0004:0005:0006:0007:0008
347 %pi6 00010002000300040005000600070008
348 %pI6c 1:2:3:4:5:6:7:8
349
350 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
351 specifiers result in a printed address with (I6) or without (i6)
352 colon-separators. Leading zeros are always used.
353
354 The additional ``c`` specifier can be used with the ``I`` specifier to
355 print a compressed IPv6 address as described by
356 https://tools.ietf.org/html/rfc5952
357
358 Passed by reference.
359
360 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
361 ---------------------------------------------------------
362
363 ::
364
365 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008
366 %piS 001.002.003.004 or 00010002000300040005000600070008
367 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8
368 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345
369 %p[Ii]S[pfschnbl]
370
371 For printing an IP address without the need to distinguish whether it's of
372 type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
373 specified through ``IS`` or ``iS``, can be passed to this format specifier.
374
375 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
376 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
377 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
378
379 In case of an IPv6 address the compressed IPv6 address as described by
380 https://tools.ietf.org/html/rfc5952 is being used if the additional
381 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
382 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
383 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
384
385 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
386 specifiers can be used as well and are ignored in case of an IPv6
387 address.
388
389 Passed by reference.
390
391 Further examples::
392
393 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789
394 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890
395 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789
396
397 UUID/GUID addresses
398 -------------------
399
400 ::
401
402 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f
403 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F
404 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f
405 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F
406
407 For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
408 ``b`` and ``B`` specifiers are used to specify a little endian order in
409 lower (l) or upper case (L) hex notation - and big endian order in lower (b)
410 or upper case (B) hex notation.
411
412 Where no additional specifiers are used the default big endian
413 order with lower case hex notation will be printed.
414
415 Passed by reference.
416
417 dentry names
418 ------------
419
420 ::
421
422 %pd{,2,3,4}
423 %pD{,2,3,4}
424
425 For printing dentry name; if we race with :c:func:`d_move`, the name might
426 be a mix of old and new ones, but it won't oops. %pd dentry is a safer
427 equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
428 last components. %pD does the same thing for struct file.
429
430 Passed by reference.
431
432 block_device names
433 ------------------
434
435 ::
436
437 %pg sda, sda1 or loop0p1
438
439 For printing name of block_device pointers.
440
441 struct va_format
442 ----------------
443
444 ::
445
446 %pV
447
448 For printing struct va_format structures. These contain a format string
449 and va_list as follows::
450
451 struct va_format {
452 const char *fmt;
453 va_list *va;
454 };
455
456 Implements a "recursive vsnprintf".
457
458 Do not use this feature without some mechanism to verify the
459 correctness of the format string and va_list arguments.
460
461 Passed by reference.
462
463 Device tree nodes
464 -----------------
465
466 ::
467
468 %pOF[fnpPcCF]
469
470
471 For printing device tree node structures. Default behaviour is
472 equivalent to %pOFf.
473
474 - f - device node full_name
475 - n - device node name
476 - p - device node phandle
477 - P - device node path spec (name + @unit)
478 - F - device node flags
479 - c - major compatible string
480 - C - full compatible string
481
482 The separator when using multiple arguments is ':'
483
484 Examples::
485
486 %pOF /foo/bar@0 - Node full name
487 %pOFf /foo/bar@0 - Same as above
488 %pOFfp /foo/bar@0:10 - Node full name + phandle
489 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name +
490 major compatible string +
491 node flags
492 D - dynamic
493 d - detached
494 P - Populated
495 B - Populated bus
496
497 Passed by reference.
498
499 Fwnode handles
500 --------------
501
502 ::
503
504 %pfw[fP]
505
506 For printing information on fwnode handles. The default is to print the full
507 node name, including the path. The modifiers are functionally equivalent to
508 %pOF above.
509
510 - f - full name of the node, including the path
511 - P - the name of the node including an address (if there is one)
512
513 Examples (ACPI)::
514
515 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name
516 %pfwP endpoint@0 - Node name
517
518 Examples (OF)::
519
520 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
521 %pfwP endpoint - Node name
522
523 Time and date
524 -------------
525
526 ::
527
528 %pt[RT] YYYY-mm-ddTHH:MM:SS
529 %pt[RT]s YYYY-mm-dd HH:MM:SS
530 %pt[RT]d YYYY-mm-dd
531 %pt[RT]t HH:MM:SS
532 %pt[RT][dt][r][s]
533
534 For printing date and time as represented by::
535
536 R struct rtc_time structure
537 T time64_t type
538
539 in human readable format.
540
541 By default year will be incremented by 1900 and month by 1.
542 Use %pt[RT]r (raw) to suppress this behaviour.
543
544 The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space)
545 instead of 'T' (Capital T) between date and time. It won't have any effect
546 when date or time is omitted.
547
548 Passed by reference.
549
550 struct clk
551 ----------
552
553 ::
554
555 %pC pll1
556 %pCn pll1
557
558 For printing struct clk structures. %pC and %pCn print the name of the clock
559 (Common Clock Framework) or a unique 32-bit ID (legacy clock framework).
560
561 Passed by reference.
562
563 bitmap and its derivatives such as cpumask and nodemask
564 -------------------------------------------------------
565
566 ::
567
568 %*pb 0779
569 %*pbl 0,3-6,8-10
570
571 For printing bitmap and its derivatives such as cpumask and nodemask,
572 %*pb outputs the bitmap with field width as the number of bits and %*pbl
573 output the bitmap as range list with field width as the number of bits.
574
575 The field width is passed by value, the bitmap is passed by reference.
576 Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
577 printing cpumask and nodemask.
578
579 Flags bitfields such as page flags, page_type, gfp_flags
580 --------------------------------------------------------
581
582 ::
583
584 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff)
585 %pGt 0xffffff7f(buddy)
586 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN
587 %pGv read|exec|mayread|maywrite|mayexec|denywrite
588
589 For printing flags bitfields as a collection of symbolic constants that
590 would construct the value. The type of flags is given by the third
591 character. Currently supported are:
592
593 - p - [p]age flags, expects value of type (``unsigned long *``)
594 - t - page [t]ype, expects value of type (``unsigned int *``)
595 - v - [v]ma_flags, expects value of type (``unsigned long *``)
596 - g - [g]fp_flags, expects value of type (``gfp_t *``)
597
598 The flag names and print order depends on the particular type.
599
600 Note that this format should not be used directly in the
601 :c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
602 functions from <trace/events/mmflags.h>.
603
604 Passed by reference.
605
606 Network device features
607 -----------------------
608
609 ::
610
611 %pNF 0x000000000000c000
612
613 For printing netdev_features_t.
614
615 Passed by reference.
616
617 V4L2 and DRM FourCC code (pixel format)
618 ---------------------------------------
619
620 ::
621
622 %p4cc
623
624 Print a FourCC code used by V4L2 or DRM, including format endianness and
625 its numerical value as hexadecimal.
626
627 Passed by reference.
628
629 Examples::
630
631 %p4cc BG12 little-endian (0x32314742)
632 %p4cc Y10 little-endian (0x20303159)
633 %p4cc NV12 big-endian (0xb231564e)
634
635 Rust
636 ----
637
638 ::
639
640 %pA
641
642 Only intended to be used from Rust code to format ``core::fmt::Arguments``.
643 Do *not* use it from C.
644
645 Thanks
646 ======
647
648 If you add other %p extensions, please extend <lib/test_printf.c> with
649 one or more test cases, if at all feasible.
650
651 Thank you for your cooperation and attention.
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.