1 =========================================
2 How to get printk format specifiers right
3 =========================================
7 :Author: Randy Dunlap <rdunlap@infradead.org>
8 :Author: Andrew Murray <amurray@mpc-data.co.uk>
16 If variable is of Type, use printk format specifier:
17 ------------------------------------------------------------
19 unsigned char %u or %x
21 unsigned short int %u or %x
25 unsigned long %lu or %lx
26 long long %lld or %llx
27 unsigned long long %llu or %llx
40 If <type> is dependent on a config option for its size (e.g., sector_t,
41 blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
42 format specifier of its largest possible type and explicitly cast to it.
46 printk("test: sector number/total blocks: %llu/%llu\n",
47 (unsigned long long)sector, (unsigned long long)blockcount);
49 Reminder: sizeof() returns type size_t.
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().
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.
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::
67 (null) data on plain NULL address
68 (efault) data on invalid address
69 (einval) invalid data on a valid address
76 %p abcdef12 or 00000000abcdef12
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.
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
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.
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.
108 Symbols/Function Pointers
109 -------------------------
113 %pS versatile_init+0x0/0x110
115 %pSR versatile_init+0x9/0x110
116 (with __builtin_extract_return_addr() translation)
117 %pB prev_fn_of_versatile_init+0x88/0x88
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.
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.
129 Probed Pointers from BPF / tracing
130 ----------------------------------
137 The ``k`` and ``u`` specifiers are used for printing prior probed memory from
138 either kernel memory (k) or user memory (u). The subsequent ``s`` specifier
139 results in printing a string. For direct use in regular vsnprintf() the (k)
140 and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(),
141 for example, it reads the memory it is pointing to without faulting.
148 %pK 01234567 or 0123456789abcdef
150 For printing kernel pointers which should be hidden from unprivileged
151 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
152 Documentation/admin-guide/sysctl/kernel.rst for more details.
154 This modifier is *only* intended when producing content of a file read by
155 userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the
156 section about %p above for discussion about how to manage hashing pointers
164 %px 01234567 or 0123456789abcdef
166 For printing pointers when you *really* want to print the address. Please
167 consider whether or not you are leaking sensitive information about the
168 kernel memory layout before printing pointers with %px. %px is functionally
169 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
170 grep'able. If in the future we need to modify the way the kernel handles
171 printing pointers we will be better equipped to find the call sites.
173 Before using %px, consider if using %p is sufficient together with enabling the
174 ``no_hash_pointers`` kernel parameter during debugging sessions (see the %p
175 description above). One valid scenario for %px might be printing information
176 immediately before a panic, which prevents any sensitive information to be
177 exploited anyway, and with %px there would be no need to reproduce the panic
178 with no_hash_pointers.
188 For printing the pointer differences, use the %t modifier for ptrdiff_t.
192 printk("test: difference between pointers: %td\n", ptr2 - ptr1);
199 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or
200 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
201 %pR [mem 0x60000000-0x6fffffff pref] or
202 [mem 0x0000000060000000-0x000000006fffffff pref]
204 For printing struct resources. The ``R`` and ``r`` specifiers result in a
205 printed resource with (R) or without (r) a decoded flags member.
209 Physical address types phys_addr_t
210 ----------------------------------
214 %pa[p] 0x01234567 or 0x0123456789abcdef
216 For printing a phys_addr_t type (and its derivatives, such as
217 resource_size_t) which can vary based on build options, regardless of the
218 width of the CPU data path.
222 DMA address types dma_addr_t
223 ----------------------------
227 %pad 0x01234567 or 0x0123456789abcdef
229 For printing a dma_addr_t type which can vary based on build options,
230 regardless of the width of the CPU data path.
234 Raw buffer as an escaped string
235 -------------------------------
241 For printing raw buffer as an escaped string. For the following buffer::
243 1b 62 20 5c 43 07 22 90 0d 5d
245 A few examples show how the conversion would be done (excluding surrounding
248 %*pE "\eb \C\a"\220\r]"
249 %*pEhp "\x1bb \C\x07"\x90\x0d]"
250 %*pEa "\e\142\040\\\103\a\042\220\r\135"
252 The conversion rules are applied according to an optional combination
253 of flags (see :c:func:`string_escape_mem` kernel documentation for the
264 By default ESCAPE_ANY_NP is used.
266 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
269 If field width is omitted then 1 byte only will be escaped.
271 Raw buffer as a hex string
272 --------------------------
277 %*phC 00:01:02: ... :3f
278 %*phD 00-01-02- ... -3f
281 For printing small buffers (up to 64 bytes long) as a hex string with a
282 certain separator. For larger buffers consider using
283 :c:func:`print_hex_dump`.
290 %pM 00:01:02:03:04:05
291 %pMR 05:04:03:02:01:00
292 %pMF 00-01-02-03-04-05
296 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
297 specifiers result in a printed address with (M) or without (m) byte
298 separators. The default byte separator is the colon (:).
300 Where FDDI addresses are concerned the ``F`` specifier can be used after
301 the ``M`` specifier to use dash (-) separators instead of the default
304 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
305 specifier to use reversed byte order suitable for visual interpretation
306 of Bluetooth addresses which are in the little endian order.
319 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
320 specifiers result in a printed address with (i4) or without (I4) leading
323 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
324 host, network, big or little endian order addresses respectively. Where
325 no specifier is provided the default network/big endian order is used.
334 %pI6 0001:0002:0003:0004:0005:0006:0007:0008
335 %pi6 00010002000300040005000600070008
336 %pI6c 1:2:3:4:5:6:7:8
338 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
339 specifiers result in a printed address with (I6) or without (i6)
340 colon-separators. Leading zeros are always used.
342 The additional ``c`` specifier can be used with the ``I`` specifier to
343 print a compressed IPv6 address as described by
344 https://tools.ietf.org/html/rfc5952
348 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
349 ---------------------------------------------------------
353 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008
354 %piS 001.002.003.004 or 00010002000300040005000600070008
355 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8
356 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345
359 For printing an IP address without the need to distinguish whether it's of
360 type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
361 specified through ``IS`` or ``iS``, can be passed to this format specifier.
363 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
364 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
365 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
367 In case of an IPv6 address the compressed IPv6 address as described by
368 https://tools.ietf.org/html/rfc5952 is being used if the additional
369 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
370 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
371 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
373 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
374 specifiers can be used as well and are ignored in case of an IPv6
381 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789
382 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890
383 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789
390 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f
391 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F
392 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f
393 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F
395 For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
396 ``b`` and ``B`` specifiers are used to specify a little endian order in
397 lower (l) or upper case (L) hex notation - and big endian order in lower (b)
398 or upper case (B) hex notation.
400 Where no additional specifiers are used the default big endian
401 order with lower case hex notation will be printed.
413 For printing dentry name; if we race with :c:func:`d_move`, the name might
414 be a mix of old and new ones, but it won't oops. %pd dentry is a safer
415 equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
416 last components. %pD does the same thing for struct file.
425 %pg sda, sda1 or loop0p1
427 For printing name of block_device pointers.
436 For printing struct va_format structures. These contain a format string
437 and va_list as follows::
444 Implements a "recursive vsnprintf".
446 Do not use this feature without some mechanism to verify the
447 correctness of the format string and va_list arguments.
459 For printing device tree node structures. Default behaviour is
462 - f - device node full_name
463 - n - device node name
464 - p - device node phandle
465 - P - device node path spec (name + @unit)
466 - F - device node flags
467 - c - major compatible string
468 - C - full compatible string
470 The separator when using multiple arguments is ':'
474 %pOF /foo/bar@0 - Node full name
475 %pOFf /foo/bar@0 - Same as above
476 %pOFfp /foo/bar@0:10 - Node full name + phandle
477 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name +
478 major compatible string +
494 For printing information on fwnode handles. The default is to print the full
495 node name, including the path. The modifiers are functionally equivalent to
498 - f - full name of the node, including the path
499 - P - the name of the node including an address (if there is one)
503 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name
504 %pfwP endpoint@0 - Node name
508 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
509 %pfwP endpoint - Node name
516 %pt[RT] YYYY-mm-ddTHH:MM:SS
521 For printing date and time as represented by::
523 R struct rtc_time structure
526 in human readable format.
528 By default year will be incremented by 1900 and month by 1.
529 Use %pt[RT]r (raw) to suppress this behaviour.
541 For printing struct clk structures. %pC and %pCn print the name of the clock
542 (Common Clock Framework) or a unique 32-bit ID (legacy clock framework).
546 bitmap and its derivatives such as cpumask and nodemask
547 -------------------------------------------------------
554 For printing bitmap and its derivatives such as cpumask and nodemask,
555 %*pb outputs the bitmap with field width as the number of bits and %*pbl
556 output the bitmap as range list with field width as the number of bits.
558 The field width is passed by value, the bitmap is passed by reference.
559 Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
560 printing cpumask and nodemask.
562 Flags bitfields such as page flags, gfp_flags
563 ---------------------------------------------
567 %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
568 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN
569 %pGv read|exec|mayread|maywrite|mayexec|denywrite
571 For printing flags bitfields as a collection of symbolic constants that
572 would construct the value. The type of flags is given by the third
573 character. Currently supported are [p]age flags, [v]ma_flags (both
574 expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
575 names and print order depends on the particular type.
577 Note that this format should not be used directly in the
578 :c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
579 functions from <trace/events/mmflags.h>.
583 Network device features
584 -----------------------
588 %pNF 0x000000000000c000
590 For printing netdev_features_t.
594 V4L2 and DRM FourCC code (pixel format)
595 ---------------------------------------
601 Print a FourCC code used by V4L2 or DRM, including format endianness and
602 its numerical value as hexadecimal.
608 %p4cc BG12 little-endian (0x32314742)
609 %p4cc Y10 little-endian (0x20303159)
610 %p4cc NV12 big-endian (0xb231564e)
615 If you add other %p extensions, please extend <lib/test_printf.c> with
616 one or more test cases, if at all feasible.
618 Thank you for your cooperation and attention.