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 signed char %d or %hhx 19 unsigned char %u or %x 20 char %u or %x 21 short int %d or %hx 22 unsigned short int %u or %x 23 int %d or %x 24 unsigned int %u or %x 25 long %ld or %lx 26 unsigned long %lu or %lx 27 long long %lld or %llx 28 unsigned long long %llu or %llx 29 size_t %zu or %zx 30 ssize_t %zd or %zx 31 s8 %d or %hhx 32 u8 %u or %x 33 s16 %d or %hx 34 u16 %u or %x 35 s32 %d or %x 36 u32 %u or %x 37 s64 %lld or %llx 38 u64 %llu or %llx 39 40 41If <type> is architecture-dependent for its size (e.g., cycles_t, tcflag_t) or 42is dependent on a config option for its size (e.g., blk_status_t), use a format 43specifier of its largest possible type and explicitly cast to it. 44 45Example:: 46 47 printk("test: latency: %llu cycles\n", (unsigned long long)time); 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 129If the pointer is within a module, the module name and optionally build ID is 130printed after the symbol name with an extra ``b`` appended to the end of the 131specifier. 132 133:: 134 135 %pS versatile_init+0x0/0x110 [module_name] 136 %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 137 %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 138 (with __builtin_extract_return_addr() translation) 139 %pBb prev_fn_of_versatile_init+0x88/0x88 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e] 140 141Probed Pointers from BPF / tracing 142---------------------------------- 143 144:: 145 146 %pks kernel string 147 %pus user string 148 149The ``k`` and ``u`` specifiers are used for printing prior probed memory from 150either kernel memory (k) or user memory (u). The subsequent ``s`` specifier 151results in printing a string. For direct use in regular vsnprintf() the (k) 152and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(), 153for example, it reads the memory it is pointing to without faulting. 154 155Kernel Pointers 156--------------- 157 158:: 159 160 %pK 01234567 or 0123456789abcdef 161 162For printing kernel pointers which should be hidden from unprivileged 163users. The behaviour of %pK depends on the kptr_restrict sysctl - see 164Documentation/admin-guide/sysctl/kernel.rst for more details. 165 166This modifier is *only* intended when producing content of a file read by 167userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the 168section about %p above for discussion about how to manage hashing pointers 169in printk(). 170 171Unmodified Addresses 172-------------------- 173 174:: 175 176 %px 01234567 or 0123456789abcdef 177 178For printing pointers when you *really* want to print the address. Please 179consider whether or not you are leaking sensitive information about the 180kernel memory layout before printing pointers with %px. %px is functionally 181equivalent to %lx (or %lu). %px is preferred because it is more uniquely 182grep'able. If in the future we need to modify the way the kernel handles 183printing pointers we will be better equipped to find the call sites. 184 185Before using %px, consider if using %p is sufficient together with enabling the 186``no_hash_pointers`` kernel parameter during debugging sessions (see the %p 187description above). One valid scenario for %px might be printing information 188immediately before a panic, which prevents any sensitive information to be 189exploited anyway, and with %px there would be no need to reproduce the panic 190with no_hash_pointers. 191 192Pointer Differences 193------------------- 194 195:: 196 197 %td 2560 198 %tx a00 199 200For printing the pointer differences, use the %t modifier for ptrdiff_t. 201 202Example:: 203 204 printk("test: difference between pointers: %td\n", ptr2 - ptr1); 205 206Struct Resources 207---------------- 208 209:: 210 211 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or 212 [mem 0x60000000 flags 0x2200] or 213 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200] 214 [mem 0x0000000060000000 flags 0x2200] 215 %pR [mem 0x60000000-0x6fffffff pref] or 216 [mem 0x60000000 pref] or 217 [mem 0x0000000060000000-0x000000006fffffff pref] 218 [mem 0x0000000060000000 pref] 219 220For printing struct resources. The ``R`` and ``r`` specifiers result in a 221printed resource with (R) or without (r) a decoded flags member. If start is 222equal to end only print the start value. 223 224Passed by reference. 225 226Physical address types phys_addr_t 227---------------------------------- 228 229:: 230 231 %pa[p] 0x01234567 or 0x0123456789abcdef 232 233For printing a phys_addr_t type (and its derivatives, such as 234resource_size_t) which can vary based on build options, regardless of the 235width of the CPU data path. 236 237Passed by reference. 238 239Struct Range 240------------ 241 242:: 243 244 %pra [range 0x0000000060000000-0x000000006fffffff] or 245 [range 0x0000000060000000] 246 247For printing struct range. struct range holds an arbitrary range of u64 248values. If start is equal to end only print the start value. 249 250Passed by reference. 251 252DMA address types dma_addr_t 253---------------------------- 254 255:: 256 257 %pad 0x01234567 or 0x0123456789abcdef 258 259For printing a dma_addr_t type which can vary based on build options, 260regardless of the width of the CPU data path. 261 262Passed by reference. 263 264Raw buffer as an escaped string 265------------------------------- 266 267:: 268 269 %*pE[achnops] 270 271For printing raw buffer as an escaped string. For the following buffer:: 272 273 1b 62 20 5c 43 07 22 90 0d 5d 274 275A few examples show how the conversion would be done (excluding surrounding 276quotes):: 277 278 %*pE "\eb \C\a"\220\r]" 279 %*pEhp "\x1bb \C\x07"\x90\x0d]" 280 %*pEa "\e\142\040\\\103\a\042\220\r\135" 281 282The conversion rules are applied according to an optional combination 283of flags (see :c:func:`string_escape_mem` kernel documentation for the 284details): 285 286 - a - ESCAPE_ANY 287 - c - ESCAPE_SPECIAL 288 - h - ESCAPE_HEX 289 - n - ESCAPE_NULL 290 - o - ESCAPE_OCTAL 291 - p - ESCAPE_NP 292 - s - ESCAPE_SPACE 293 294By default ESCAPE_ANY_NP is used. 295 296ESCAPE_ANY_NP is the sane choice for many cases, in particularly for 297printing SSIDs. 298 299If field width is omitted then 1 byte only will be escaped. 300 301Raw buffer as a hex string 302-------------------------- 303 304:: 305 306 %*ph 00 01 02 ... 3f 307 %*phC 00:01:02: ... :3f 308 %*phD 00-01-02- ... -3f 309 %*phN 000102 ... 3f 310 311For printing small buffers (up to 64 bytes long) as a hex string with a 312certain separator. For larger buffers consider using 313:c:func:`print_hex_dump`. 314 315MAC/FDDI addresses 316------------------ 317 318:: 319 320 %pM 00:01:02:03:04:05 321 %pMR 05:04:03:02:01:00 322 %pMF 00-01-02-03-04-05 323 %pm 000102030405 324 %pmR 050403020100 325 %p[mM][FR][U] 326 327For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` 328specifiers result in a printed address with (M) or without (m) byte 329separators. The default byte separator is the colon (:). 330 331Where FDDI addresses are concerned the ``F`` specifier can be used after 332the ``M`` specifier to use dash (-) separators instead of the default 333separator. 334 335For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` 336specifier to use reversed byte order suitable for visual interpretation 337of Bluetooth addresses which are in the little endian order. 338 339When ``U`` is passed, the result is printed in the upper case. 340 341Passed by reference. 342 343IPv4 addresses 344-------------- 345 346:: 347 348 %pI4 1.2.3.4 349 %pi4 001.002.003.004 350 %p[Ii]4[hnbl] 351 352For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` 353specifiers result in a printed address with (i4) or without (I4) leading 354zeros. 355 356The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify 357host, network, big or little endian order addresses respectively. Where 358no specifier is provided the default network/big endian order is used. 359 360Passed by reference. 361 362IPv6 addresses 363-------------- 364 365:: 366 367 %pI6 0001:0002:0003:0004:0005:0006:0007:0008 368 %pi6 00010002000300040005000600070008 369 %pI6c 1:2:3:4:5:6:7:8 370 371For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` 372specifiers result in a printed address with (I6) or without (i6) 373colon-separators. Leading zeros are always used. 374 375The additional ``c`` specifier can be used with the ``I`` specifier to 376print a compressed IPv6 address as described by 377https://tools.ietf.org/html/rfc5952 378 379Passed by reference. 380 381IPv4/IPv6 addresses (generic, with port, flowinfo, scope) 382--------------------------------------------------------- 383 384:: 385 386 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 387 %piS 001.002.003.004 or 00010002000300040005000600070008 388 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 389 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 390 %p[Ii]S[pfschnbl] 391 392For printing an IP address without the need to distinguish whether it's of 393type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, 394specified through ``IS`` or ``iS``, can be passed to this format specifier. 395 396The additional ``p``, ``f``, and ``s`` specifiers are used to specify port 397(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, 398flowinfo a ``/`` and scope a ``%``, each followed by the actual value. 399 400In case of an IPv6 address the compressed IPv6 address as described by 401https://tools.ietf.org/html/rfc5952 is being used if the additional 402specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in 403case of additional specifiers ``p``, ``f`` or ``s`` as suggested by 404https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 405 406In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` 407specifiers can be used as well and are ignored in case of an IPv6 408address. 409 410Passed by reference. 411 412Further examples:: 413 414 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 415 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 416 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 417 418UUID/GUID addresses 419------------------- 420 421:: 422 423 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f 424 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F 425 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f 426 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F 427 428For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, 429``b`` and ``B`` specifiers are used to specify a little endian order in 430lower (l) or upper case (L) hex notation - and big endian order in lower (b) 431or upper case (B) hex notation. 432 433Where no additional specifiers are used the default big endian 434order with lower case hex notation will be printed. 435 436Passed by reference. 437 438dentry names 439------------ 440 441:: 442 443 %pd{,2,3,4} 444 %pD{,2,3,4} 445 446For printing dentry name; if we race with :c:func:`d_move`, the name might 447be a mix of old and new ones, but it won't oops. %pd dentry is a safer 448equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` 449last components. %pD does the same thing for struct file. 450 451Passed by reference. 452 453block_device names 454------------------ 455 456:: 457 458 %pg sda, sda1 or loop0p1 459 460For printing name of block_device pointers. 461 462struct va_format 463---------------- 464 465:: 466 467 %pV 468 469For printing struct va_format structures. These contain a format string 470and va_list as follows:: 471 472 struct va_format { 473 const char *fmt; 474 va_list *va; 475 }; 476 477Implements a "recursive vsnprintf". 478 479Do not use this feature without some mechanism to verify the 480correctness of the format string and va_list arguments. 481 482Passed by reference. 483 484Device tree nodes 485----------------- 486 487:: 488 489 %pOF[fnpPcCF] 490 491 492For printing device tree node structures. Default behaviour is 493equivalent to %pOFf. 494 495 - f - device node full_name 496 - n - device node name 497 - p - device node phandle 498 - P - device node path spec (name + @unit) 499 - F - device node flags 500 - c - major compatible string 501 - C - full compatible string 502 503The separator when using multiple arguments is ':' 504 505Examples:: 506 507 %pOF /foo/bar@0 - Node full name 508 %pOFf /foo/bar@0 - Same as above 509 %pOFfp /foo/bar@0:10 - Node full name + phandle 510 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + 511 major compatible string + 512 node flags 513 D - dynamic 514 d - detached 515 P - Populated 516 B - Populated bus 517 518Passed by reference. 519 520Fwnode handles 521-------------- 522 523:: 524 525 %pfw[fP] 526 527For printing information on an fwnode_handle. The default is to print the full 528node name, including the path. The modifiers are functionally equivalent to 529%pOF above. 530 531 - f - full name of the node, including the path 532 - P - the name of the node including an address (if there is one) 533 534Examples (ACPI):: 535 536 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name 537 %pfwP endpoint@0 - Node name 538 539Examples (OF):: 540 541 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name 542 %pfwP endpoint - Node name 543 544Time and date 545------------- 546 547:: 548 549 %pt[RT] YYYY-mm-ddTHH:MM:SS 550 %pt[RT]s YYYY-mm-dd HH:MM:SS 551 %pt[RT]d YYYY-mm-dd 552 %pt[RT]t HH:MM:SS 553 %ptSp <seconds>.<nanoseconds> 554 %pt[RST][dt][r][s] 555 556For printing date and time as represented by:: 557 558 R content of struct rtc_time 559 S content of struct timespec64 560 T time64_t type 561 562in human readable format. 563 564By default year will be incremented by 1900 and month by 1. 565Use %pt[RT]r (raw) to suppress this behaviour. 566 567The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space) 568instead of 'T' (Capital T) between date and time. It won't have any effect 569when date or time is omitted. 570 571The %ptSp is equivalent to %lld.%09ld for the content of the struct timespec64. 572When the other specifiers are given, it becomes the respective equivalent of 573%ptT[dt][r][s].%09ld. In other words, the seconds are being printed in 574the human readable format followed by a dot and nanoseconds. 575 576Passed by reference. 577 578struct clk 579---------- 580 581:: 582 583 %pC pll1 584 585For printing struct clk structures. %pC prints the name of the clock 586(Common Clock Framework) or a unique 32-bit ID (legacy clock framework). 587 588Passed by reference. 589 590bitmap and its derivatives such as cpumask and nodemask 591------------------------------------------------------- 592 593:: 594 595 %*pb 0779 596 %*pbl 0,3-6,8-10 597 598For printing bitmap and its derivatives such as cpumask and nodemask, 599%*pb outputs the bitmap with field width as the number of bits and %*pbl 600output the bitmap as range list with field width as the number of bits. 601 602The field width is passed by value, the bitmap is passed by reference. 603Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease 604printing cpumask and nodemask. 605 606Flags bitfields such as page flags and gfp_flags 607-------------------------------------------------------- 608 609:: 610 611 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) 612 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 613 %pGv read|exec|mayread|maywrite|mayexec|denywrite 614 615For printing flags bitfields as a collection of symbolic constants that 616would construct the value. The type of flags is given by the third 617character. Currently supported are: 618 619 - p - [p]age flags, expects value of type (``unsigned long *``) 620 - v - [v]ma_flags, expects value of type (``unsigned long *``) 621 - g - [g]fp_flags, expects value of type (``gfp_t *``) 622 623The flag names and print order depends on the particular type. 624 625Note that this format should not be used directly in the 626:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() 627functions from <trace/events/mmflags.h>. 628 629Passed by reference. 630 631Network device features 632----------------------- 633 634:: 635 636 %pNF 0x000000000000c000 637 638For printing netdev_features_t. 639 640Passed by reference. 641 642V4L2 and DRM FourCC code (pixel format) 643--------------------------------------- 644 645:: 646 647 %p4cc 648 649Print a FourCC code used by V4L2 or DRM, including format endianness and 650its numerical value as hexadecimal. 651 652Passed by reference. 653 654Examples:: 655 656 %p4cc BG12 little-endian (0x32314742) 657 %p4cc Y10 little-endian (0x20303159) 658 %p4cc NV12 big-endian (0xb231564e) 659 660Generic FourCC code 661------------------- 662 663:: 664 %p4c[h[R]lb] gP00 (0x67503030) 665 666Print a generic FourCC code, as both ASCII characters and its numerical 667value as hexadecimal. 668 669The generic FourCC code is always printed in the big-endian format, 670the most significant byte first. This is the opposite of V4L/DRM FourCCs. 671 672The additional ``h``, ``hR``, ``l``, and ``b`` specifiers define what 673endianness is used to load the stored bytes. The data might be interpreted 674using the host, reversed host byte order, little-endian, or big-endian. 675 676Passed by reference. 677 678Examples for a little-endian machine, given &(u32)0x67503030:: 679 680 %p4ch gP00 (0x67503030) 681 %p4chR 00Pg (0x30305067) 682 %p4cl gP00 (0x67503030) 683 %p4cb 00Pg (0x30305067) 684 685Examples for a big-endian machine, given &(u32)0x67503030:: 686 687 %p4ch gP00 (0x67503030) 688 %p4chR 00Pg (0x30305067) 689 %p4cl 00Pg (0x30305067) 690 %p4cb gP00 (0x67503030) 691 692Rust 693---- 694 695:: 696 697 %pA 698 699Only intended to be used from Rust code to format ``core::fmt::Arguments``. 700Do *not* use it from C. 701 702Thanks 703====== 704 705If you add other %p extensions, please extend <lib/tests/printf_kunit.c> 706with one or more test cases, if at all feasible. 707 708Thank you for your cooperation and attention. 709