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