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