blob: 4451ef501936133998b059d5b0482328845e02ba [file] [log] [blame]
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -03001=========================================
2How to get printk format specifiers right
3=========================================
4
Ricardo CaƱuelo90c165f02020-04-03 11:36:17 +02005.. _printk-specifiers:
6
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -03007:Author: Randy Dunlap <rdunlap@infradead.org>
8:Author: Andrew Murray <amurray@mpc-data.co.uk>
9
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110010
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -030011Integer types
12=============
13
14::
15
16 If variable is of Type, use printk format specifier:
17 ------------------------------------------------------------
Andy Shevchenko243e212f2023-07-03 17:58:39 +030018 signed char %d or %hhx
Joe Perchescbacb5a2019-09-06 14:11:51 -070019 unsigned char %u or %x
Andy Shevchenko243e212f2023-07-03 17:58:39 +030020 char %u or %x
Andy Shevchenko46d57a72023-07-03 17:58:38 +030021 short int %d or %hx
Joe Perchescbacb5a2019-09-06 14:11:51 -070022 unsigned short int %u or %x
Randy Dunlapb67ad182008-11-12 13:26:55 -080023 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
Andy Shevchenko46d57a72023-07-03 17:58:38 +030031 s8 %d or %hhx
Joe Perchescbacb5a2019-09-06 14:11:51 -070032 u8 %u or %x
Andy Shevchenko46d57a72023-07-03 17:58:38 +030033 s16 %d or %hx
Joe Perchescbacb5a2019-09-06 14:11:51 -070034 u16 %u or %x
Geert Uytterhoevene8a7ba52015-04-15 16:17:17 -070035 s32 %d or %x
36 u32 %u or %x
37 s64 %lld or %llx
38 u64 %llu or %llx
39
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110040
Carlos Llamasd7c176e2021-06-09 19:50:58 +000041If <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.
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -030044
45Example::
Geert Uytterhoevene8a7ba52015-04-15 16:17:17 -070046
Carlos Llamasd7c176e2021-06-09 19:50:58 +000047 printk("test: latency: %llu cycles\n", (unsigned long long)time);
Geert Uytterhoevene8a7ba52015-04-15 16:17:17 -070048
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110049Reminder: sizeof() returns type size_t.
Geert Uytterhoevene8a7ba52015-04-15 16:17:17 -070050
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110051The 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
Rasmus Villemoesd7ec9a02015-11-06 16:30:35 -080053unsupported specifier or length qualifier results in a WARN and early
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110054return from vsnprintf().
Randy Dunlapb67ad182008-11-12 13:26:55 -080055
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110056Pointer types
Tobin C. Hardingad67b742017-11-01 15:32:23 +110057=============
58
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110059A 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
Petr Mladek3e5903e2019-04-17 13:53:48 +020063Some 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
Petr Mladek635720a2019-04-17 13:53:49 +020069 (einval) invalid data on a valid address
Petr Mladek3e5903e2019-04-17 13:53:48 +020070
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110071Plain Pointers
72--------------
Tobin C. Hardingad67b742017-11-01 15:32:23 +110073
74::
75
76 %p abcdef12 or 00000000abcdef12
77
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110078Pointers 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
Joel Stanley156383b2018-03-22 15:53:36 +103081the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
Vlastimil Babkaa48849e2021-02-25 17:46:39 +010082gathers 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.
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +110095
Rasmus Villemoes57f56772019-10-15 21:07:05 +020096Error 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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300108Symbols/Function Pointers
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100109-------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300110
111::
Andrew Murray04c55712011-06-15 12:57:09 -0700112
Sergey Senozhatsky04b8eb72017-12-06 13:36:49 +0900113 %pS versatile_init+0x0/0x110
114 %ps versatile_init
Joe Perchesb0d33c22012-12-12 10:18:50 -0800115 %pSR versatile_init+0x9/0x110
116 (with __builtin_extract_return_addr() translation)
Andrew Murray04c55712011-06-15 12:57:09 -0700117 %pB prev_fn_of_versatile_init+0x88/0x88
118
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100119
Sergey Senozhatsky04b8eb72017-12-06 13:36:49 +0900120The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic
Linus Torvaldsab486bc2018-02-01 13:36:15 -0800121format. They result in the symbol name with (S) or without (s)
Sergey Senozhatsky04b8eb72017-12-06 13:36:49 +0900122offsets. If KALLSYMS are disabled then the symbol address is printed instead.
Helge Dellerd6957f332017-08-15 11:34:19 +0200123
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300124The ``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
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100127when tail-calls are used and marked with the noreturn GCC attribute.
Andrew Murray04c55712011-06-15 12:57:09 -0700128
Stephen Boyd92945232021-07-07 18:09:20 -0700129If 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::
Ioana Ciornei5b42d0b2021-07-22 13:03:53 +0300134
Stephen Boyd92945232021-07-07 18:09:20 -0700135 %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
Daniel Borkmannb2a52122020-05-15 12:11:18 +0200141Probed 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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300155Kernel Pointers
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100156---------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300157
158::
Andrew Murray04c55712011-06-15 12:57:09 -0700159
Tobin C. Harding553d8e82017-11-23 10:55:24 +1100160 %pK 01234567 or 0123456789abcdef
Andrew Murray04c55712011-06-15 12:57:09 -0700161
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300162For printing kernel pointers which should be hidden from unprivileged
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100163users. The behaviour of %pK depends on the kptr_restrict sysctl - see
Mauro Carvalho Chehab57043242019-04-22 16:48:00 -0300164Documentation/admin-guide/sysctl/kernel.rst for more details.
Andrew Murray04c55712011-06-15 12:57:09 -0700165
Vlastimil Babkaa48849e2021-02-25 17:46:39 +0100166This 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
Tobin C. Harding7b1924a2017-11-23 10:59:45 +1100171Unmodified Addresses
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100172--------------------
Tobin C. Harding7b1924a2017-11-23 10:59:45 +1100173
174::
175
176 %px 01234567 or 0123456789abcdef
177
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100178For printing pointers when you *really* want to print the address. Please
Tobin C. Harding7b1924a2017-11-23 10:59:45 +1100179consider whether or not you are leaking sensitive information about the
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100180kernel 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.
Tobin C. Harding7b1924a2017-11-23 10:59:45 +1100184
Vlastimil Babkaa48849e2021-02-25 17:46:39 +0100185Before 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
Miles Chen88288ed2019-10-01 18:04:49 +0800192Pointer 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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300206Struct Resources
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100207----------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300208
209::
Andrew Murray04c55712011-06-15 12:57:09 -0700210
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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300216For printing struct resources. The ``R`` and ``r`` specifiers result in a
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100217printed resource with (R) or without (r) a decoded flags member.
218
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300219Passed by reference.
Andrew Murray04c55712011-06-15 12:57:09 -0700220
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100221Physical address types phys_addr_t
222----------------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300223
224::
Stepan Moskovchenko7d799212013-02-21 16:43:09 -0800225
Joe Perchesaaf07622014-01-23 15:54:17 -0800226 %pa[p] 0x01234567 or 0x0123456789abcdef
Stepan Moskovchenko7d799212013-02-21 16:43:09 -0800227
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100228For printing a phys_addr_t type (and its derivatives, such as
229resource_size_t) which can vary based on build options, regardless of the
230width of the CPU data path.
Stepan Moskovchenko7d799212013-02-21 16:43:09 -0800231
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100232Passed by reference.
233
234DMA address types dma_addr_t
235----------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300236
237::
Joe Perchesaaf07622014-01-23 15:54:17 -0800238
239 %pad 0x01234567 or 0x0123456789abcdef
240
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100241For printing a dma_addr_t type which can vary based on build options,
242regardless of the width of the CPU data path.
243
244Passed by reference.
Joe Perchesaaf07622014-01-23 15:54:17 -0800245
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300246Raw buffer as an escaped string
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100247-------------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300248
249::
Andy Shevchenko71dca952014-10-13 15:55:18 -0700250
251 %*pE[achnops]
252
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300253For printing raw buffer as an escaped string. For the following buffer::
Andy Shevchenko71dca952014-10-13 15:55:18 -0700254
255 1b 62 20 5c 43 07 22 90 0d 5d
256
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100257A few examples show how the conversion would be done (excluding surrounding
258quotes)::
Andy Shevchenko71dca952014-10-13 15:55:18 -0700259
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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300264The conversion rules are applied according to an optional combination
265of flags (see :c:func:`string_escape_mem` kernel documentation for the
266details):
Andy Shevchenko71dca952014-10-13 15:55:18 -0700267
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100268 - 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
Andy Shevchenko71dca952014-10-13 15:55:18 -0700275
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300276By default ESCAPE_ANY_NP is used.
Andy Shevchenko71dca952014-10-13 15:55:18 -0700277
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300278ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
279printing SSIDs.
280
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100281If field width is omitted then 1 byte only will be escaped.
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300282
283Raw buffer as a hex string
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100284--------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300285
286::
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800287
Andy Shevchenko31550a12012-07-30 14:40:27 -0700288 %*ph 00 01 02 ... 3f
289 %*phC 00:01:02: ... :3f
290 %*phD 00-01-02- ... -3f
291 %*phN 000102 ... 3f
292
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100293For printing small buffers (up to 64 bytes long) as a hex string with a
294certain separator. For larger buffers consider using
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300295:c:func:`print_hex_dump`.
Andy Shevchenko31550a12012-07-30 14:40:27 -0700296
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300297MAC/FDDI addresses
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100298------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300299
300::
Andrew Murray04c55712011-06-15 12:57:09 -0700301
302 %pM 00:01:02:03:04:05
Andrei Emeltchenko76597ff92012-07-30 14:40:23 -0700303 %pMR 05:04:03:02:01:00
Andrew Murray04c55712011-06-15 12:57:09 -0700304 %pMF 00-01-02-03-04-05
305 %pm 000102030405
Andy Shevchenko7c591542012-10-04 17:12:33 -0700306 %pmR 050403020100
Andrew Murray04c55712011-06-15 12:57:09 -0700307
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300308For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100309specifiers result in a printed address with (M) or without (m) byte
310separators. The default byte separator is the colon (:).
Andrew Murray04c55712011-06-15 12:57:09 -0700311
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300312Where FDDI addresses are concerned the ``F`` specifier can be used after
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100313the ``M`` specifier to use dash (-) separators instead of the default
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300314separator.
Andrew Murray04c55712011-06-15 12:57:09 -0700315
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300316For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
317specifier to use reversed byte order suitable for visual interpretation
318of Bluetooth addresses which are in the little endian order.
Andrei Emeltchenko76597ff92012-07-30 14:40:23 -0700319
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300320Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700321
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300322IPv4 addresses
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100323--------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300324
325::
Andrew Murray04c55712011-06-15 12:57:09 -0700326
327 %pI4 1.2.3.4
328 %pi4 001.002.003.004
Daniel Borkmann8ecada12013-06-28 15:49:39 +0200329 %p[Ii]4[hnbl]
Andrew Murray04c55712011-06-15 12:57:09 -0700330
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300331For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100332specifiers result in a printed address with (i4) or without (I4) leading
333zeros.
Andrew Murray04c55712011-06-15 12:57:09 -0700334
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300335The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
336host, network, big or little endian order addresses respectively. Where
337no specifier is provided the default network/big endian order is used.
Andrew Murray04c55712011-06-15 12:57:09 -0700338
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300339Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700340
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300341IPv6 addresses
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100342--------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300343
344::
Andrew Murray04c55712011-06-15 12:57:09 -0700345
346 %pI6 0001:0002:0003:0004:0005:0006:0007:0008
347 %pi6 00010002000300040005000600070008
348 %pI6c 1:2:3:4:5:6:7:8
349
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300350For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100351specifiers result in a printed address with (I6) or without (i6)
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300352colon-separators. Leading zeros are always used.
Andrew Murray04c55712011-06-15 12:57:09 -0700353
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300354The additional ``c`` specifier can be used with the ``I`` specifier to
355print a compressed IPv6 address as described by
Alexander A. Klimov8eda94b2020-07-02 22:05:36 +0200356https://tools.ietf.org/html/rfc5952
Andrew Murray04c55712011-06-15 12:57:09 -0700357
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300358Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700359
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300360IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100361---------------------------------------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300362
363::
Daniel Borkmann10679642013-06-28 19:49:39 +0200364
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
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100371For printing an IP address without the need to distinguish whether it's of
372type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300373specified through ``IS`` or ``iS``, can be passed to this format specifier.
Daniel Borkmann10679642013-06-28 19:49:39 +0200374
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300375The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
376(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
377flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
Daniel Borkmann10679642013-06-28 19:49:39 +0200378
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300379In case of an IPv6 address the compressed IPv6 address as described by
Alexander A. Klimov8eda94b2020-07-02 22:05:36 +0200380https://tools.ietf.org/html/rfc5952 is being used if the additional
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300381specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
382case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
383https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
Daniel Borkmann10679642013-06-28 19:49:39 +0200384
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300385In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
386specifiers can be used as well and are ignored in case of an IPv6
387address.
Daniel Borkmann10679642013-06-28 19:49:39 +0200388
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300389Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700390
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300391Further examples::
Daniel Borkmann10679642013-06-28 19:49:39 +0200392
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
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300397UUID/GUID addresses
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100398-------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300399
400::
Andrew Murray04c55712011-06-15 12:57:09 -0700401
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
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100407For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
408``b`` and ``B`` specifiers are used to specify a little endian order in
409lower (l) or upper case (L) hex notation - and big endian order in lower (b)
410or upper case (B) hex notation.
Andrew Murray04c55712011-06-15 12:57:09 -0700411
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300412Where no additional specifiers are used the default big endian
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100413order with lower case hex notation will be printed.
Andrew Murray04c55712011-06-15 12:57:09 -0700414
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300415Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700416
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300417dentry names
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100418------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300419
420::
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800421
Al Viro4b6ccca2013-09-03 12:00:44 -0400422 %pd{,2,3,4}
423 %pD{,2,3,4}
424
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100425For printing dentry name; if we race with :c:func:`d_move`, the name might
426be a mix of old and new ones, but it won't oops. %pd dentry is a safer
427equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
428last components. %pD does the same thing for struct file.
Al Viro4b6ccca2013-09-03 12:00:44 -0400429
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300430Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700431
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300432block_device names
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100433------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300434
435::
Dmitry Monakhov1031bc52015-04-13 16:31:35 +0400436
437 %pg sda, sda1 or loop0p1
438
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300439For printing name of block_device pointers.
Dmitry Monakhov1031bc52015-04-13 16:31:35 +0400440
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300441struct va_format
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100442----------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300443
444::
Andrew Murray04c55712011-06-15 12:57:09 -0700445
446 %pV
447
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300448For printing struct va_format structures. These contain a format string
449and va_list as follows::
Andrew Murray04c55712011-06-15 12:57:09 -0700450
451 struct va_format {
452 const char *fmt;
453 va_list *va;
454 };
455
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300456Implements a "recursive vsnprintf".
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800457
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300458Do not use this feature without some mechanism to verify the
459correctness of the format string and va_list arguments.
Randy Dunlapb67ad182008-11-12 13:26:55 -0800460
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300461Passed by reference.
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700462
Geert Uytterhoeven94ac8f22018-10-08 13:08:48 +0200463Device tree nodes
464-----------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300465
466::
467
Pantelis Antoniouce4fecf2015-01-21 19:06:14 +0200468 %pOF[fnpPcCF]
469
Pantelis Antoniouce4fecf2015-01-21 19:06:14 +0200470
Geert Uytterhoeven94ac8f22018-10-08 13:08:48 +0200471For printing device tree node structures. Default behaviour is
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100472equivalent 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
482The separator when using multiple arguments is ':'
483
484Examples::
Pantelis Antoniouce4fecf2015-01-21 19:06:14 +0200485
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
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100497Passed by reference.
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300498
Sakari Ailus3bd32d62019-10-03 15:32:18 +0300499Fwnode handles
500--------------
501
502::
503
504 %pfw[fP]
505
506For printing information on fwnode handles. The default is to print the full
507node 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
513Examples (ACPI)::
514
515 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name
516 %pfwP endpoint@0 - Node name
517
518Examples (OF)::
519
520 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name
521 %pfwP endpoint - Node name
522
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300523Time and date
524-------------
Andy Shevchenko4d42c442018-12-04 23:23:11 +0200525
526::
527
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300528 %pt[RT] YYYY-mm-ddTHH:MM:SS
Andy Shevchenko20bc8c12021-05-11 18:39:55 +0300529 %pt[RT]s YYYY-mm-dd HH:MM:SS
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300530 %pt[RT]d YYYY-mm-dd
531 %pt[RT]t HH:MM:SS
Andy Shevchenko20bc8c12021-05-11 18:39:55 +0300532 %pt[RT][dt][r][s]
Andy Shevchenko4d42c442018-12-04 23:23:11 +0200533
Daniel W. S. Almeidab7f41992020-07-18 13:51:02 -0300534For printing date and time as represented by::
535
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300536 R struct rtc_time structure
537 T time64_t type
Daniel W. S. Almeidab7f41992020-07-18 13:51:02 -0300538
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300539in human readable format.
Andy Shevchenko4d42c442018-12-04 23:23:11 +0200540
Andy Shevchenko7daac5b2020-04-15 20:00:44 +0300541By default year will be incremented by 1900 and month by 1.
542Use %pt[RT]r (raw) to suppress this behaviour.
Andy Shevchenko4d42c442018-12-04 23:23:11 +0200543
Andy Shevchenko20bc8c12021-05-11 18:39:55 +0300544The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space)
545instead of 'T' (Capital T) between date and time. It won't have any effect
546when date or time is omitted.
547
Andy Shevchenko4d42c442018-12-04 23:23:11 +0200548Passed by reference.
549
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300550struct clk
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100551----------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300552
553::
Geert Uytterhoeven900cca22015-04-15 16:17:20 -0700554
555 %pC pll1
556 %pCn pll1
Geert Uytterhoeven900cca22015-04-15 16:17:20 -0700557
Geert Uytterhoevenec12bc22018-10-11 10:42:48 +0200558For 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).
Geert Uytterhoeven900cca22015-04-15 16:17:20 -0700560
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300561Passed by reference.
Geert Uytterhoeven900cca22015-04-15 16:17:20 -0700562
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300563bitmap and its derivatives such as cpumask and nodemask
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100564-------------------------------------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300565
566::
Wang Longd0724962015-02-26 03:28:25 +0000567
568 %*pb 0779
569 %*pbl 0,3-6,8-10
570
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300571For printing bitmap and its derivatives such as cpumask and nodemask,
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100572%*pb outputs the bitmap with field width as the number of bits and %*pbl
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300573output the bitmap as range list with field width as the number of bits.
Wang Longd0724962015-02-26 03:28:25 +0000574
Geert Uytterhoeven04d06082020-11-10 15:41:21 +0100575The field width is passed by value, the bitmap is passed by reference.
576Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease
577printing cpumask and nodemask.
Randy Dunlapb67ad182008-11-12 13:26:55 -0800578
Hyeonggon Yoo4c85c0b2023-01-30 13:25:13 +0900579Flags bitfields such as page flags, page_type, gfp_flags
580--------------------------------------------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300581
582::
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700583
Petr Mladek6a7ca802021-10-27 14:48:40 +0200584 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff)
Hyeonggon Yoo4c85c0b2023-01-30 13:25:13 +0900585 %pGt 0xffffff7f(buddy)
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700586 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN
587 %pGv read|exec|mayread|maywrite|mayexec|denywrite
588
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300589For printing flags bitfields as a collection of symbolic constants that
590would construct the value. The type of flags is given by the third
Hyeonggon Yoo4c85c0b2023-01-30 13:25:13 +0900591character. 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
598The flag names and print order depends on the particular type.
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700599
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100600Note that this format should not be used directly in the
601:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
602functions from <trace/events/mmflags.h>.
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700603
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300604Passed by reference.
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700605
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300606Network device features
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100607-----------------------
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300608
609::
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800610
611 %pNF 0x000000000000c000
612
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300613For printing netdev_features_t.
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800614
Mauro Carvalho Chehab3b033382017-05-16 22:27:11 -0300615Passed by reference.
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800616
Sakari Ailusaf612e42021-02-16 17:57:20 +0200617V4L2 and DRM FourCC code (pixel format)
618---------------------------------------
619
620::
621
622 %p4cc
623
624Print a FourCC code used by V4L2 or DRM, including format endianness and
625its numerical value as hexadecimal.
626
627Passed by reference.
628
629Examples::
630
631 %p4cc BG12 little-endian (0x32314742)
632 %p4cc Y10 little-endian (0x20303159)
633 %p4cc NV12 big-endian (0xb231564e)
634
Gary Guo787983d2021-07-03 17:38:57 +0200635Rust
636----
637
638::
639
640 %pA
641
642Only intended to be used from Rust code to format ``core::fmt::Arguments``.
643Do *not* use it from C.
644
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100645Thanks
646======
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800647
Tobin C. Hardingb3ed2322017-12-20 08:17:15 +1100648If you add other %p extensions, please extend <lib/test_printf.c> with
649one or more test cases, if at all feasible.
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800650
Randy Dunlapb67ad182008-11-12 13:26:55 -0800651Thank you for your cooperation and attention.