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