1========================================= 2How to get printk format specifiers right 3========================================= 4 5.. _printk-specifiers: 6 7:Author: Randy Dunlap <rdunlap@infradead.org> 8:Author: Andrew Murray <amurray@mpc-data.co.uk> 9 10 11Integer types 12============= 13 14:: 15 16 If variable is of Type, use printk format specifier: 17 ------------------------------------------------------------ 18 char %d or %x 19 unsigned char %u or %x 20 short int %d or %x 21 unsigned short int %u or %x 22 int %d or %x 23 unsigned int %u or %x 24 long %ld or %lx 25 unsigned long %lu or %lx 26 long long %lld or %llx 27 unsigned long long %llu or %llx 28 size_t %zu or %zx 29 ssize_t %zd or %zx 30 s8 %d or %x 31 u8 %u or %x 32 s16 %d or %x 33 u16 %u or %x 34 s32 %d or %x 35 u32 %u or %x 36 s64 %lld or %llx 37 u64 %llu or %llx 38 39 40If <type> is dependent on a config option for its size (e.g., sector_t, 41blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a 42format specifier of its largest possible type and explicitly cast to it. 43 44Example:: 45 46 printk("test: sector number/total blocks: %llu/%llu\n", 47 (unsigned long long)sector, (unsigned long long)blockcount); 48 49Reminder: sizeof() returns type size_t. 50 51The kernel's printf does not support %n. Floating point formats (%e, %f, 52%g, %a) are also not recognized, for obvious reasons. Use of any 53unsupported specifier or length qualifier results in a WARN and early 54return from vsnprintf(). 55 56Pointer types 57============= 58 59A raw pointer value may be printed with %p which will hash the address 60before printing. The kernel also supports extended specifiers for printing 61pointers of different types. 62 63Some of the extended specifiers print the data on the given address instead 64of printing the address itself. In this case, the following error messages 65might be printed instead of the unreachable information:: 66 67 (null) data on plain NULL address 68 (efault) data on invalid address 69 (einval) invalid data on a valid address 70 71Plain Pointers 72-------------- 73 74:: 75 76 %p abcdef12 or 00000000abcdef12 77 78Pointers printed without a specifier extension (i.e unadorned %p) are 79hashed to prevent leaking information about the kernel memory layout. This 80has the added benefit of providing a unique identifier. On 64-bit machines 81the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it 82gathers enough entropy. 83 84When possible, use specialised modifiers such as %pS or %pB (described below) 85to avoid the need of providing an unhashed address that has to be interpreted 86post-hoc. If not possible, and the aim of printing the address is to provide 87more information for debugging, use %p and boot the kernel with the 88``no_hash_pointers`` parameter during debugging, which will print all %p 89addresses unmodified. If you *really* always want the unmodified address, see 90%px below. 91 92If (and only if) you are printing addresses as a content of a virtual file in 93e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a 94userspace process, use the %pK modifier described below instead of %p or %px. 95 96Error Pointers 97-------------- 98 99:: 100 101 %pe -ENOSPC 102 103For printing error pointers (i.e. a pointer for which IS_ERR() is true) 104as a symbolic error name. Error values for which no symbolic name is 105known are printed in decimal, while a non-ERR_PTR passed as the 106argument to %pe gets treated as ordinary %p. 107 108Symbols/Function Pointers 109------------------------- 110 111:: 112 113 %pS versatile_init+0x0/0x110 114 %ps versatile_init 115 %pSR versatile_init+0x9/0x110 116 (with __builtin_extract_return_addr() translation) 117 %pB prev_fn_of_versatile_init+0x88/0x88 118 119 120The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic 121format. They result in the symbol name with (S) or without (s) 122offsets. If KALLSYMS are disabled then the symbol address is printed instead. 123 124The ``B`` specifier results in the symbol name with offsets and should be 125used when printing stack backtraces. The specifier takes into 126consideration the effect of compiler optimisations which may occur 127when tail-calls are used and marked with the noreturn GCC attribute. 128 129Probed Pointers from BPF / tracing 130---------------------------------- 131 132:: 133 134 %pks kernel string 135 %pus user string 136 137The ``k`` and ``u`` specifiers are used for printing prior probed memory from 138either kernel memory (k) or user memory (u). The subsequent ``s`` specifier 139results in printing a string. For direct use in regular vsnprintf() the (k) 140and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(), 141for example, it reads the memory it is pointing to without faulting. 142 143Kernel Pointers 144--------------- 145 146:: 147 148 %pK 01234567 or 0123456789abcdef 149 150For printing kernel pointers which should be hidden from unprivileged 151users. The behaviour of %pK depends on the kptr_restrict sysctl - see 152Documentation/admin-guide/sysctl/kernel.rst for more details. 153 154This modifier is *only* intended when producing content of a file read by 155userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the 156section about %p above for discussion about how to manage hashing pointers 157in printk(). 158 159Unmodified Addresses 160-------------------- 161 162:: 163 164 %px 01234567 or 0123456789abcdef 165 166For printing pointers when you *really* want to print the address. Please 167consider whether or not you are leaking sensitive information about the 168kernel memory layout before printing pointers with %px. %px is functionally 169equivalent to %lx (or %lu). %px is preferred because it is more uniquely 170grep'able. If in the future we need to modify the way the kernel handles 171printing pointers we will be better equipped to find the call sites. 172 173Before using %px, consider if using %p is sufficient together with enabling the 174``no_hash_pointers`` kernel parameter during debugging sessions (see the %p 175description above). One valid scenario for %px might be printing information 176immediately before a panic, which prevents any sensitive information to be 177exploited anyway, and with %px there would be no need to reproduce the panic 178with no_hash_pointers. 179 180Pointer Differences 181------------------- 182 183:: 184 185 %td 2560 186 %tx a00 187 188For printing the pointer differences, use the %t modifier for ptrdiff_t. 189 190Example:: 191 192 printk("test: difference between pointers: %td\n", ptr2 - ptr1); 193 194Struct Resources 195---------------- 196 197:: 198 199 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or 200 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] 201 %pR [mem 0x60000000-0x6fffffff pref] or 202 [mem 0x0000000060000000-0x000000006fffffff pref] 203 204For printing struct resources. The ``R`` and ``r`` specifiers result in a 205printed resource with (R) or without (r) a decoded flags member. 206 207Passed by reference. 208 209Physical address types phys_addr_t 210---------------------------------- 211 212:: 213 214 %pa[p] 0x01234567 or 0x0123456789abcdef 215 216For printing a phys_addr_t type (and its derivatives, such as 217resource_size_t) which can vary based on build options, regardless of the 218width of the CPU data path. 219 220Passed by reference. 221 222DMA address types dma_addr_t 223---------------------------- 224 225:: 226 227 %pad 0x01234567 or 0x0123456789abcdef 228 229For printing a dma_addr_t type which can vary based on build options, 230regardless of the width of the CPU data path. 231 232Passed by reference. 233 234Raw buffer as an escaped string 235------------------------------- 236 237:: 238 239 %*pE[achnops] 240 241For printing raw buffer as an escaped string. For the following buffer:: 242 243 1b 62 20 5c 43 07 22 90 0d 5d 244 245A few examples show how the conversion would be done (excluding surrounding 246quotes):: 247 248 %*pE "\eb \C\a"\220\r]" 249 %*pEhp "\x1bb \C\x07"\x90\x0d]" 250 %*pEa "\e\142\040\\\103\a\042\220\r\135" 251 252The conversion rules are applied according to an optional combination 253of flags (see :c:func:`string_escape_mem` kernel documentation for the 254details): 255 256 - a - ESCAPE_ANY 257 - c - ESCAPE_SPECIAL 258 - h - ESCAPE_HEX 259 - n - ESCAPE_NULL 260 - o - ESCAPE_OCTAL 261 - p - ESCAPE_NP 262 - s - ESCAPE_SPACE 263 264By default ESCAPE_ANY_NP is used. 265 266ESCAPE_ANY_NP is the sane choice for many cases, in particularly for 267printing SSIDs. 268 269If field width is omitted then 1 byte only will be escaped. 270 271Raw buffer as a hex string 272-------------------------- 273 274:: 275 276 %*ph 00 01 02 ... 3f 277 %*phC 00:01:02: ... :3f 278 %*phD 00-01-02- ... -3f 279 %*phN 000102 ... 3f 280 281For printing small buffers (up to 64 bytes long) as a hex string with a 282certain separator. For larger buffers consider using 283:c:func:`print_hex_dump`. 284 285MAC/FDDI addresses 286------------------ 287 288:: 289 290 %pM 00:01:02:03:04:05 291 %pMR 05:04:03:02:01:00 292 %pMF 00-01-02-03-04-05 293 %pm 000102030405 294 %pmR 050403020100 295 296For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` 297specifiers result in a printed address with (M) or without (m) byte 298separators. The default byte separator is the colon (:). 299 300Where FDDI addresses are concerned the ``F`` specifier can be used after 301the ``M`` specifier to use dash (-) separators instead of the default 302separator. 303 304For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` 305specifier to use reversed byte order suitable for visual interpretation 306of Bluetooth addresses which are in the little endian order. 307 308Passed by reference. 309 310IPv4 addresses 311-------------- 312 313:: 314 315 %pI4 1.2.3.4 316 %pi4 001.002.003.004 317 %p[Ii]4[hnbl] 318 319For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` 320specifiers result in a printed address with (i4) or without (I4) leading 321zeros. 322 323The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify 324host, network, big or little endian order addresses respectively. Where 325no specifier is provided the default network/big endian order is used. 326 327Passed by reference. 328 329IPv6 addresses 330-------------- 331 332:: 333 334 %pI6 0001:0002:0003:0004:0005:0006:0007:0008 335 %pi6 00010002000300040005000600070008 336 %pI6c 1:2:3:4:5:6:7:8 337 338For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` 339specifiers result in a printed address with (I6) or without (i6) 340colon-separators. Leading zeros are always used. 341 342The additional ``c`` specifier can be used with the ``I`` specifier to 343print a compressed IPv6 address as described by 344https://tools.ietf.org/html/rfc5952 345 346Passed by reference. 347 348IPv4/IPv6 addresses (generic, with port, flowinfo, scope) 349--------------------------------------------------------- 350 351:: 352 353 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 354 %piS 001.002.003.004 or 00010002000300040005000600070008 355 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 356 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 357 %p[Ii]S[pfschnbl] 358 359For printing an IP address without the need to distinguish whether it's of 360type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, 361specified through ``IS`` or ``iS``, can be passed to this format specifier. 362 363The additional ``p``, ``f``, and ``s`` specifiers are used to specify port 364(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, 365flowinfo a ``/`` and scope a ``%``, each followed by the actual value. 366 367In case of an IPv6 address the compressed IPv6 address as described by 368https://tools.ietf.org/html/rfc5952 is being used if the additional 369specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in 370case of additional specifiers ``p``, ``f`` or ``s`` as suggested by 371https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 372 373In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` 374specifiers can be used as well and are ignored in case of an IPv6 375address. 376 377Passed by reference. 378 379Further examples:: 380 381 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 382 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 383 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 384 385UUID/GUID addresses 386------------------- 387 388:: 389 390 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f 391 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F 392 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f 393 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F 394 395For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, 396``b`` and ``B`` specifiers are used to specify a little endian order in 397lower (l) or upper case (L) hex notation - and big endian order in lower (b) 398or upper case (B) hex notation. 399 400Where no additional specifiers are used the default big endian 401order with lower case hex notation will be printed. 402 403Passed by reference. 404 405dentry names 406------------ 407 408:: 409 410 %pd{,2,3,4} 411 %pD{,2,3,4} 412 413For printing dentry name; if we race with :c:func:`d_move`, the name might 414be a mix of old and new ones, but it won't oops. %pd dentry is a safer 415equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` 416last components. %pD does the same thing for struct file. 417 418Passed by reference. 419 420block_device names 421------------------ 422 423:: 424 425 %pg sda, sda1 or loop0p1 426 427For printing name of block_device pointers. 428 429struct va_format 430---------------- 431 432:: 433 434 %pV 435 436For printing struct va_format structures. These contain a format string 437and va_list as follows:: 438 439 struct va_format { 440 const char *fmt; 441 va_list *va; 442 }; 443 444Implements a "recursive vsnprintf". 445 446Do not use this feature without some mechanism to verify the 447correctness of the format string and va_list arguments. 448 449Passed by reference. 450 451Device tree nodes 452----------------- 453 454:: 455 456 %pOF[fnpPcCF] 457 458 459For printing device tree node structures. Default behaviour is 460equivalent to %pOFf. 461 462 - f - device node full_name 463 - n - device node name 464 - p - device node phandle 465 - P - device node path spec (name + @unit) 466 - F - device node flags 467 - c - major compatible string 468 - C - full compatible string 469 470The separator when using multiple arguments is ':' 471 472Examples:: 473 474 %pOF /foo/bar@0 - Node full name 475 %pOFf /foo/bar@0 - Same as above 476 %pOFfp /foo/bar@0:10 - Node full name + phandle 477 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + 478 major compatible string + 479 node flags 480 D - dynamic 481 d - detached 482 P - Populated 483 B - Populated bus 484 485Passed by reference. 486 487Fwnode handles 488-------------- 489 490:: 491 492 %pfw[fP] 493 494For printing information on fwnode handles. The default is to print the full 495node name, including the path. The modifiers are functionally equivalent to 496%pOF above. 497 498 - f - full name of the node, including the path 499 - P - the name of the node including an address (if there is one) 500 501Examples (ACPI):: 502 503 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name 504 %pfwP endpoint@0 - Node name 505 506Examples (OF):: 507 508 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name 509 %pfwP endpoint - Node name 510 511Time and date 512------------- 513 514:: 515 516 %pt[RT] YYYY-mm-ddTHH:MM:SS 517 %pt[RT]d YYYY-mm-dd 518 %pt[RT]t HH:MM:SS 519 %pt[RT][dt][r] 520 521For printing date and time as represented by:: 522 523 R struct rtc_time structure 524 T time64_t type 525 526in human readable format. 527 528By default year will be incremented by 1900 and month by 1. 529Use %pt[RT]r (raw) to suppress this behaviour. 530 531Passed by reference. 532 533struct clk 534---------- 535 536:: 537 538 %pC pll1 539 %pCn pll1 540 541For printing struct clk structures. %pC and %pCn print the name of the clock 542(Common Clock Framework) or a unique 32-bit ID (legacy clock framework). 543 544Passed by reference. 545 546bitmap and its derivatives such as cpumask and nodemask 547------------------------------------------------------- 548 549:: 550 551 %*pb 0779 552 %*pbl 0,3-6,8-10 553 554For printing bitmap and its derivatives such as cpumask and nodemask, 555%*pb outputs the bitmap with field width as the number of bits and %*pbl 556output the bitmap as range list with field width as the number of bits. 557 558The field width is passed by value, the bitmap is passed by reference. 559Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease 560printing cpumask and nodemask. 561 562Flags bitfields such as page flags, gfp_flags 563--------------------------------------------- 564 565:: 566 567 %pGp referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff 568 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 569 %pGv read|exec|mayread|maywrite|mayexec|denywrite 570 571For printing flags bitfields as a collection of symbolic constants that 572would construct the value. The type of flags is given by the third 573character. Currently supported are [p]age flags, [v]ma_flags (both 574expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag 575names and print order depends on the particular type. 576 577Note that this format should not be used directly in the 578:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() 579functions from <trace/events/mmflags.h>. 580 581Passed by reference. 582 583Network device features 584----------------------- 585 586:: 587 588 %pNF 0x000000000000c000 589 590For printing netdev_features_t. 591 592Passed by reference. 593 594V4L2 and DRM FourCC code (pixel format) 595--------------------------------------- 596 597:: 598 599 %p4cc 600 601Print a FourCC code used by V4L2 or DRM, including format endianness and 602its numerical value as hexadecimal. 603 604Passed by reference. 605 606Examples:: 607 608 %p4cc BG12 little-endian (0x32314742) 609 %p4cc Y10 little-endian (0x20303159) 610 %p4cc NV12 big-endian (0xb231564e) 611 612Thanks 613====== 614 615If you add other %p extensions, please extend <lib/test_printf.c> with 616one or more test cases, if at all feasible. 617 618Thank you for your cooperation and attention. 619