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 architecture-dependent for its size (e.g., cycles_t, tcflag_t) or
41 is dependent on a config option for its size (e.g., blk_status_t), use a format
42 specifier of its largest possible type and explicitly cast to it.
46 printk("test: latency: %llu cycles\n", (unsigned long long)time);
48 Reminder: sizeof() returns type size_t.
50 The kernel's printf does not support %n. Floating point formats (%e, %f,
51 %g, %a) are also not recognized, for obvious reasons. Use of any
52 unsupported specifier or length qualifier results in a WARN and early
53 return from vsnprintf().
58 A raw pointer value may be printed with %p which will hash the address
59 before printing. The kernel also supports extended specifiers for printing
60 pointers of different types.
62 Some of the extended specifiers print the data on the given address instead
63 of printing the address itself. In this case, the following error messages
64 might be printed instead of the unreachable information::
66 (null) data on plain NULL address
67 (efault) data on invalid address
68 (einval) invalid data on a valid address
75 %p abcdef12 or 00000000abcdef12
77 Pointers printed without a specifier extension (i.e unadorned %p) are
78 hashed to prevent leaking information about the kernel memory layout. This
79 has the added benefit of providing a unique identifier. On 64-bit machines
80 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
81 gathers enough entropy.
83 When possible, use specialised modifiers such as %pS or %pB (described below)
84 to avoid the need of providing an unhashed address that has to be interpreted
85 post-hoc. If not possible, and the aim of printing the address is to provide
86 more information for debugging, use %p and boot the kernel with the
87 ``no_hash_pointers`` parameter during debugging, which will print all %p
88 addresses unmodified. If you *really* always want the unmodified address, see
91 If (and only if) you are printing addresses as a content of a virtual file in
92 e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a
93 userspace process, use the %pK modifier described below instead of %p or %px.
102 For printing error pointers (i.e. a pointer for which IS_ERR() is true)
103 as a symbolic error name. Error values for which no symbolic name is
104 known are printed in decimal, while a non-ERR_PTR passed as the
105 argument to %pe gets treated as ordinary %p.
107 Symbols/Function Pointers
108 -------------------------
112 %pS versatile_init+0x0/0x110
114 %pSR versatile_init+0x9/0x110
115 (with __builtin_extract_return_addr() translation)
116 %pB prev_fn_of_versatile_init+0x88/0x88
119 The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic
120 format. They result in the symbol name with (S) or without (s)
121 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
123 The ``B`` specifier results in the symbol name with offsets and should be
124 used when printing stack backtraces. The specifier takes into
125 consideration the effect of compiler optimisations which may occur
126 when tail-calls are used and marked with the noreturn GCC attribute.
128 Probed Pointers from BPF / tracing
129 ----------------------------------
136 The ``k`` and ``u`` specifiers are used for printing prior probed memory from
137 either kernel memory (k) or user memory (u). The subsequent ``s`` specifier
138 results in printing a string. For direct use in regular vsnprintf() the (k)
139 and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(),
140 for example, it reads the memory it is pointing to without faulting.
147 %pK 01234567 or 0123456789abcdef
149 For printing kernel pointers which should be hidden from unprivileged
150 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
151 Documentation/admin-guide/sysctl/kernel.rst for more details.
153 This modifier is *only* intended when producing content of a file read by
154 userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the
155 section about %p above for discussion about how to manage hashing pointers
163 %px 01234567 or 0123456789abcdef
165 For printing pointers when you *really* want to print the address. Please
166 consider whether or not you are leaking sensitive information about the
167 kernel memory layout before printing pointers with %px. %px is functionally
168 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
169 grep'able. If in the future we need to modify the way the kernel handles
170 printing pointers we will be better equipped to find the call sites.
172 Before using %px, consider if using %p is sufficient together with enabling the
173 ``no_hash_pointers`` kernel parameter during debugging sessions (see the %p
174 description above). One valid scenario for %px might be printing information
175 immediately before a panic, which prevents any sensitive information to be
176 exploited anyway, and with %px there would be no need to reproduce the panic
177 with no_hash_pointers.
187 For printing the pointer differences, use the %t modifier for ptrdiff_t.
191 printk("test: difference between pointers: %td\n", ptr2 - ptr1);
198 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or
199 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
200 %pR [mem 0x60000000-0x6fffffff pref] or
201 [mem 0x0000000060000000-0x000000006fffffff pref]
203 For printing struct resources. The ``R`` and ``r`` specifiers result in a
204 printed resource with (R) or without (r) a decoded flags member.
208 Physical address types phys_addr_t
209 ----------------------------------
213 %pa[p] 0x01234567 or 0x0123456789abcdef
215 For printing a phys_addr_t type (and its derivatives, such as
216 resource_size_t) which can vary based on build options, regardless of the
217 width of the CPU data path.
221 DMA address types dma_addr_t
222 ----------------------------
226 %pad 0x01234567 or 0x0123456789abcdef
228 For printing a dma_addr_t type which can vary based on build options,
229 regardless of the width of the CPU data path.
233 Raw buffer as an escaped string
234 -------------------------------
240 For printing raw buffer as an escaped string. For the following buffer::
242 1b 62 20 5c 43 07 22 90 0d 5d
244 A few examples show how the conversion would be done (excluding surrounding
247 %*pE "\eb \C\a"\220\r]"
248 %*pEhp "\x1bb \C\x07"\x90\x0d]"
249 %*pEa "\e\142\040\\\103\a\042\220\r\135"
251 The conversion rules are applied according to an optional combination
252 of flags (see :c:func:`string_escape_mem` kernel documentation for the
263 By default ESCAPE_ANY_NP is used.
265 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
268 If field width is omitted then 1 byte only will be escaped.
270 Raw buffer as a hex string
271 --------------------------
276 %*phC 00:01:02: ... :3f
277 %*phD 00-01-02- ... -3f
280 For printing small buffers (up to 64 bytes long) as a hex string with a
281 certain separator. For larger buffers consider using
282 :c:func:`print_hex_dump`.
289 %pM 00:01:02:03:04:05
290 %pMR 05:04:03:02:01:00
291 %pMF 00-01-02-03-04-05
295 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
296 specifiers result in a printed address with (M) or without (m) byte
297 separators. The default byte separator is the colon (:).
299 Where FDDI addresses are concerned the ``F`` specifier can be used after
300 the ``M`` specifier to use dash (-) separators instead of the default
303 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
304 specifier to use reversed byte order suitable for visual interpretation
305 of Bluetooth addresses which are in the little endian order.
318 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
319 specifiers result in a printed address with (i4) or without (I4) leading
322 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
323 host, network, big or little endian order addresses respectively. Where
324 no specifier is provided the default network/big endian order is used.
333 %pI6 0001:0002:0003:0004:0005:0006:0007:0008
334 %pi6 00010002000300040005000600070008
335 %pI6c 1:2:3:4:5:6:7:8
337 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
338 specifiers result in a printed address with (I6) or without (i6)
339 colon-separators. Leading zeros are always used.
341 The additional ``c`` specifier can be used with the ``I`` specifier to
342 print a compressed IPv6 address as described by
343 https://tools.ietf.org/html/rfc5952
347 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
348 ---------------------------------------------------------
352 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008
353 %piS 001.002.003.004 or 00010002000300040005000600070008
354 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8
355 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345
358 For printing an IP address without the need to distinguish whether it's of
359 type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
360 specified through ``IS`` or ``iS``, can be passed to this format specifier.
362 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
363 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
364 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
366 In case of an IPv6 address the compressed IPv6 address as described by
367 https://tools.ietf.org/html/rfc5952 is being used if the additional
368 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
369 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
370 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
372 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
373 specifiers can be used as well and are ignored in case of an IPv6
380 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789
381 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890
382 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789
389 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f
390 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F
391 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f
392 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F
394 For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
395 ``b`` and ``B`` specifiers are used to specify a little endian order in
396 lower (l) or upper case (L) hex notation - and big endian order in lower (b)
397 or upper case (B) hex notation.
399 Where no additional specifiers are used the default big endian
400 order with lower case hex notation will be printed.
412 For printing dentry name; if we race with :c:func:`d_move`, the name might
413 be a mix of old and new ones, but it won't oops. %pd dentry is a safer
414 equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
415 last components. %pD does the same thing for struct file.
424 %pg sda, sda1 or loop0p1
426 For printing name of block_device pointers.
435 For printing struct va_format structures. These contain a format string
436 and va_list as follows::
443 Implements a "recursive vsnprintf".
445 Do not use this feature without some mechanism to verify the
446 correctness of the format string and va_list arguments.
458 For printing device tree node structures. Default behaviour is
461 - f - device node full_name
462 - n - device node name
463 - p - device node phandle
464 - P - device node path spec (name + @unit)
465 - F - device node flags
466 - c - major compatible string
467 - C - full compatible string
469 The separator when using multiple arguments is ':'
473 %pOF /foo/bar@0 - Node full name
474 %pOFf /foo/bar@0 - Same as above
475 %pOFfp /foo/bar@0:10 - Node full name + phandle
476 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name +
477 major compatible string +
493 For printing information on fwnode handles. The default is to print the full
494 node name, including the path. The modifiers are functionally equivalent to
497 - f - full name of the node, including the path
498 - P - the name of the node including an address (if there is one)
502 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name
503 %pfwP endpoint@0 - Node name
507 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
508 %pfwP endpoint - Node name
515 %pt[RT] YYYY-mm-ddTHH:MM:SS
520 For printing date and time as represented by::
522 R struct rtc_time structure
525 in human readable format.
527 By default year will be incremented by 1900 and month by 1.
528 Use %pt[RT]r (raw) to suppress this behaviour.
540 For printing struct clk structures. %pC and %pCn print the name of the clock
541 (Common Clock Framework) or a unique 32-bit ID (legacy clock framework).
545 bitmap and its derivatives such as cpumask and nodemask
546 -------------------------------------------------------
553 For printing bitmap and its derivatives such as cpumask and nodemask,
554 %*pb outputs the bitmap with field width as the number of bits and %*pbl
555 output the bitmap as range list with field width as the number of bits.
557 The field width is passed by value, the bitmap is passed by reference.
558 Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
559 printing cpumask and nodemask.
561 Flags bitfields such as page flags, gfp_flags
562 ---------------------------------------------
566 %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff
567 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN
568 %pGv read|exec|mayread|maywrite|mayexec|denywrite
570 For printing flags bitfields as a collection of symbolic constants that
571 would construct the value. The type of flags is given by the third
572 character. Currently supported are [p]age flags, [v]ma_flags (both
573 expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
574 names and print order depends on the particular type.
576 Note that this format should not be used directly in the
577 :c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
578 functions from <trace/events/mmflags.h>.
582 Network device features
583 -----------------------
587 %pNF 0x000000000000c000
589 For printing netdev_features_t.
593 V4L2 and DRM FourCC code (pixel format)
594 ---------------------------------------
600 Print a FourCC code used by V4L2 or DRM, including format endianness and
601 its numerical value as hexadecimal.
607 %p4cc BG12 little-endian (0x32314742)
608 %p4cc Y10 little-endian (0x20303159)
609 %p4cc NV12 big-endian (0xb231564e)
614 If you add other %p extensions, please extend <lib/test_printf.c> with
615 one or more test cases, if at all feasible.
617 Thank you for your cooperation and attention.