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