]>
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 | ||
3b033380 MCC |
88 | Kernel Pointers |
89 | =============== | |
04c55715 | 90 | |
3b033380 | 91 | :: |
04c55715 | 92 | |
553d8e8b | 93 | %pK 01234567 or 0123456789abcdef |
04c55715 | 94 | |
3b033380 MCC |
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 | ================ | |
04c55715 | 101 | |
3b033380 | 102 | :: |
04c55715 AM |
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 | ||
3b033380 MCC |
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 | ======================================== | |
04c55715 | 115 | |
3b033380 | 116 | :: |
7d799210 | 117 | |
aaf07621 | 118 | %pa[p] 0x01234567 or 0x0123456789abcdef |
7d799210 | 119 | |
3b033380 MCC |
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. | |
7d799210 | 123 | |
3b033380 MCC |
124 | DMA addresses types ``dma_addr_t`` |
125 | ================================== | |
126 | ||
127 | :: | |
aaf07621 JP |
128 | |
129 | %pad 0x01234567 or 0x0123456789abcdef | |
130 | ||
3b033380 MCC |
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 | =============================== | |
aaf07621 | 136 | |
3b033380 | 137 | :: |
71dca95d AS |
138 | |
139 | %*pE[achnops] | |
140 | ||
3b033380 | 141 | For printing raw buffer as an escaped string. For the following buffer:: |
71dca95d AS |
142 | |
143 | 1b 62 20 5c 43 07 22 90 0d 5d | |
144 | ||
3b033380 MCC |
145 | few examples show how the conversion would be done (the result string |
146 | without surrounding quotes):: | |
71dca95d AS |
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 | ||
3b033380 MCC |
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 | |
71dca95d | 163 | |
3b033380 | 164 | By default ESCAPE_ANY_NP is used. |
71dca95d | 165 | |
3b033380 MCC |
166 | ESCAPE_ANY_NP is the sane choice for many cases, in particularly for |
167 | printing SSIDs. | |
71dca95d | 168 | |
3b033380 MCC |
169 | If field width is omitted the 1 byte only will be escaped. |
170 | ||
171 | Raw buffer as a hex string | |
172 | ========================== | |
173 | ||
174 | :: | |
5e4ee7b1 | 175 | |
31550a16 AS |
176 | %*ph 00 01 02 ... 3f |
177 | %*phC 00:01:02: ... :3f | |
178 | %*phD 00-01-02- ... -3f | |
179 | %*phN 000102 ... 3f | |
180 | ||
3b033380 MCC |
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 | ================== | |
31550a16 | 187 | |
3b033380 | 188 | :: |
04c55715 AM |
189 | |
190 | %pM 00:01:02:03:04:05 | |
76597ff9 | 191 | %pMR 05:04:03:02:01:00 |
04c55715 AM |
192 | %pMF 00-01-02-03-04-05 |
193 | %pm 000102030405 | |
7c59154e | 194 | %pmR 050403020100 |
04c55715 | 195 | |
3b033380 MCC |
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 (``:``). | |
04c55715 | 199 | |
3b033380 MCC |
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. | |
04c55715 | 203 | |
3b033380 MCC |
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. | |
76597ff9 | 207 | |
3b033380 MCC |
208 | Passed by reference. |
209 | ||
210 | IPv4 addresses | |
211 | ============== | |
7330660e | 212 | |
3b033380 | 213 | :: |
04c55715 AM |
214 | |
215 | %pI4 1.2.3.4 | |
216 | %pi4 001.002.003.004 | |
8ecada16 | 217 | %p[Ii]4[hnbl] |
04c55715 | 218 | |
3b033380 MCC |
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. | |
04c55715 | 222 | |
3b033380 MCC |
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. | |
04c55715 | 226 | |
3b033380 | 227 | Passed by reference. |
7330660e | 228 | |
3b033380 MCC |
229 | IPv6 addresses |
230 | ============== | |
231 | ||
232 | :: | |
04c55715 AM |
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 | ||
3b033380 MCC |
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. | |
04c55715 | 241 | |
3b033380 MCC |
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 | |
04c55715 | 245 | |
3b033380 | 246 | Passed by reference. |
7330660e | 247 | |
3b033380 MCC |
248 | IPv4/IPv6 addresses (generic, with port, flowinfo, scope) |
249 | ========================================================= | |
250 | ||
251 | :: | |
10679643 DB |
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 | ||
3b033380 MCC |
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. | |
10679643 | 262 | |
3b033380 MCC |
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. | |
10679643 | 266 | |
3b033380 MCC |
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 | |
10679643 | 272 | |
3b033380 MCC |
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. | |
10679643 | 276 | |
3b033380 | 277 | Passed by reference. |
7330660e | 278 | |
3b033380 | 279 | Further examples:: |
10679643 DB |
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 | ||
3b033380 MCC |
285 | UUID/GUID addresses |
286 | =================== | |
287 | ||
288 | :: | |
04c55715 AM |
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 | ||
3b033380 MCC |
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. | |
04c55715 | 299 | |
3b033380 MCC |
300 | Where no additional specifiers are used the default big endian |
301 | order with lower case hex characters will be printed. | |
04c55715 | 302 | |
3b033380 MCC |
303 | Passed by reference. |
304 | ||
305 | dentry names | |
306 | ============ | |
7330660e | 307 | |
3b033380 | 308 | :: |
5e4ee7b1 | 309 | |
4b6ccca7 AV |
310 | %pd{,2,3,4} |
311 | %pD{,2,3,4} | |
312 | ||
3b033380 MCC |
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. | |
4b6ccca7 | 317 | |
3b033380 | 318 | Passed by reference. |
7330660e | 319 | |
3b033380 MCC |
320 | block_device names |
321 | ================== | |
322 | ||
323 | :: | |
1031bc58 DM |
324 | |
325 | %pg sda, sda1 or loop0p1 | |
326 | ||
3b033380 MCC |
327 | For printing name of block_device pointers. |
328 | ||
329 | struct va_format | |
330 | ================ | |
1031bc58 | 331 | |
3b033380 | 332 | :: |
04c55715 AM |
333 | |
334 | %pV | |
335 | ||
3b033380 MCC |
336 | For printing struct va_format structures. These contain a format string |
337 | and va_list as follows:: | |
04c55715 AM |
338 | |
339 | struct va_format { | |
340 | const char *fmt; | |
341 | va_list *va; | |
342 | }; | |
343 | ||
3b033380 | 344 | Implements a "recursive vsnprintf". |
5e4ee7b1 | 345 | |
3b033380 MCC |
346 | Do not use this feature without some mechanism to verify the |
347 | correctness of the format string and va_list arguments. | |
b67ad18b | 348 | |
3b033380 MCC |
349 | Passed by reference. |
350 | ||
351 | kobjects | |
352 | ======== | |
353 | ||
354 | :: | |
7330660e | 355 | |
ce4fecf1 PA |
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 | ||
3b033380 MCC |
391 | |
392 | struct clk | |
393 | ========== | |
394 | ||
395 | :: | |
900cca29 GU |
396 | |
397 | %pC pll1 | |
398 | %pCn pll1 | |
399 | %pCr 1560000000 | |
400 | ||
3b033380 MCC |
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. | |
900cca29 | 404 | |
3b033380 | 405 | Passed by reference. |
900cca29 | 406 | |
3b033380 MCC |
407 | bitmap and its derivatives such as cpumask and nodemask |
408 | ======================================================= | |
409 | ||
410 | :: | |
d0724961 WL |
411 | |
412 | %*pb 0779 | |
413 | %*pbl 0,3-6,8-10 | |
414 | ||
3b033380 MCC |
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. | |
d0724961 | 418 | |
3b033380 MCC |
419 | Passed by reference. |
420 | ||
421 | Flags bitfields such as page flags, gfp_flags | |
422 | ============================================= | |
b67ad18b | 423 | |
3b033380 | 424 | :: |
edf14cdb VB |
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 | ||
3b033380 MCC |
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. | |
edf14cdb | 435 | |
3b033380 MCC |
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>. | |
edf14cdb | 439 | |
3b033380 MCC |
440 | Passed by reference. |
441 | ||
442 | Network device features | |
443 | ======================= | |
edf14cdb | 444 | |
3b033380 | 445 | :: |
5e4ee7b1 MK |
446 | |
447 | %pNF 0x000000000000c000 | |
448 | ||
3b033380 | 449 | For printing netdev_features_t. |
5e4ee7b1 | 450 | |
3b033380 | 451 | Passed by reference. |
5e4ee7b1 | 452 | |
3b033380 | 453 | If you add other ``%p`` extensions, please extend lib/test_printf.c with |
d7ec9a05 | 454 | one or more test cases, if at all feasible. |
5e4ee7b1 | 455 | |
5e4ee7b1 | 456 | |
b67ad18b | 457 | Thank you for your cooperation and attention. |