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