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