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