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 326For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` 327specifiers result in a printed address with (M) or without (m) byte 328separators. The default byte separator is the colon (:). 329 330Where FDDI addresses are concerned the ``F`` specifier can be used after 331the ``M`` specifier to use dash (-) separators instead of the default 332separator. 333 334For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` 335specifier to use reversed byte order suitable for visual interpretation 336of Bluetooth addresses which are in the little endian order. 337 338Passed by reference. 339 340IPv4 addresses 341-------------- 342 343:: 344 345 %pI4 1.2.3.4 346 %pi4 001.002.003.004 347 %p[Ii]4[hnbl] 348 349For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` 350specifiers result in a printed address with (i4) or without (I4) leading 351zeros. 352 353The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify 354host, network, big or little endian order addresses respectively. Where 355no specifier is provided the default network/big endian order is used. 356 357Passed by reference. 358 359IPv6 addresses 360-------------- 361 362:: 363 364 %pI6 0001:0002:0003:0004:0005:0006:0007:0008 365 %pi6 00010002000300040005000600070008 366 %pI6c 1:2:3:4:5:6:7:8 367 368For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` 369specifiers result in a printed address with (I6) or without (i6) 370colon-separators. Leading zeros are always used. 371 372The additional ``c`` specifier can be used with the ``I`` specifier to 373print a compressed IPv6 address as described by 374https://tools.ietf.org/html/rfc5952 375 376Passed by reference. 377 378IPv4/IPv6 addresses (generic, with port, flowinfo, scope) 379--------------------------------------------------------- 380 381:: 382 383 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 384 %piS 001.002.003.004 or 00010002000300040005000600070008 385 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 386 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 387 %p[Ii]S[pfschnbl] 388 389For printing an IP address without the need to distinguish whether it's of 390type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, 391specified through ``IS`` or ``iS``, can be passed to this format specifier. 392 393The additional ``p``, ``f``, and ``s`` specifiers are used to specify port 394(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, 395flowinfo a ``/`` and scope a ``%``, each followed by the actual value. 396 397In case of an IPv6 address the compressed IPv6 address as described by 398https://tools.ietf.org/html/rfc5952 is being used if the additional 399specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in 400case of additional specifiers ``p``, ``f`` or ``s`` as suggested by 401https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 402 403In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` 404specifiers can be used as well and are ignored in case of an IPv6 405address. 406 407Passed by reference. 408 409Further examples:: 410 411 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 412 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 413 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 414 415UUID/GUID addresses 416------------------- 417 418:: 419 420 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f 421 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F 422 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f 423 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F 424 425For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, 426``b`` and ``B`` specifiers are used to specify a little endian order in 427lower (l) or upper case (L) hex notation - and big endian order in lower (b) 428or upper case (B) hex notation. 429 430Where no additional specifiers are used the default big endian 431order with lower case hex notation will be printed. 432 433Passed by reference. 434 435dentry names 436------------ 437 438:: 439 440 %pd{,2,3,4} 441 %pD{,2,3,4} 442 443For printing dentry name; if we race with :c:func:`d_move`, the name might 444be a mix of old and new ones, but it won't oops. %pd dentry is a safer 445equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` 446last components. %pD does the same thing for struct file. 447 448Passed by reference. 449 450block_device names 451------------------ 452 453:: 454 455 %pg sda, sda1 or loop0p1 456 457For printing name of block_device pointers. 458 459struct va_format 460---------------- 461 462:: 463 464 %pV 465 466For printing struct va_format structures. These contain a format string 467and va_list as follows:: 468 469 struct va_format { 470 const char *fmt; 471 va_list *va; 472 }; 473 474Implements a "recursive vsnprintf". 475 476Do not use this feature without some mechanism to verify the 477correctness of the format string and va_list arguments. 478 479Passed by reference. 480 481Device tree nodes 482----------------- 483 484:: 485 486 %pOF[fnpPcCF] 487 488 489For printing device tree node structures. Default behaviour is 490equivalent to %pOFf. 491 492 - f - device node full_name 493 - n - device node name 494 - p - device node phandle 495 - P - device node path spec (name + @unit) 496 - F - device node flags 497 - c - major compatible string 498 - C - full compatible string 499 500The separator when using multiple arguments is ':' 501 502Examples:: 503 504 %pOF /foo/bar@0 - Node full name 505 %pOFf /foo/bar@0 - Same as above 506 %pOFfp /foo/bar@0:10 - Node full name + phandle 507 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + 508 major compatible string + 509 node flags 510 D - dynamic 511 d - detached 512 P - Populated 513 B - Populated bus 514 515Passed by reference. 516 517Fwnode handles 518-------------- 519 520:: 521 522 %pfw[fP] 523 524For printing information on an fwnode_handle. The default is to print the full 525node name, including the path. The modifiers are functionally equivalent to 526%pOF above. 527 528 - f - full name of the node, including the path 529 - P - the name of the node including an address (if there is one) 530 531Examples (ACPI):: 532 533 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name 534 %pfwP endpoint@0 - Node name 535 536Examples (OF):: 537 538 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name 539 %pfwP endpoint - Node name 540 541Time and date 542------------- 543 544:: 545 546 %pt[RT] YYYY-mm-ddTHH:MM:SS 547 %pt[RT]s YYYY-mm-dd HH:MM:SS 548 %pt[RT]d YYYY-mm-dd 549 %pt[RT]t HH:MM:SS 550 %ptSp <seconds>.<nanoseconds> 551 %pt[RST][dt][r][s] 552 553For printing date and time as represented by:: 554 555 R content of struct rtc_time 556 S content of struct timespec64 557 T time64_t type 558 559in human readable format. 560 561By default year will be incremented by 1900 and month by 1. 562Use %pt[RT]r (raw) to suppress this behaviour. 563 564The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space) 565instead of 'T' (Capital T) between date and time. It won't have any effect 566when date or time is omitted. 567 568The %ptSp is equivalent to %lld.%09ld for the content of the struct timespec64. 569When the other specifiers are given, it becomes the respective equivalent of 570%ptT[dt][r][s].%09ld. In other words, the seconds are being printed in 571the human readable format followed by a dot and nanoseconds. 572 573Passed by reference. 574 575struct clk 576---------- 577 578:: 579 580 %pC pll1 581 582For printing struct clk structures. %pC prints the name of the clock 583(Common Clock Framework) or a unique 32-bit ID (legacy clock framework). 584 585Passed by reference. 586 587bitmap and its derivatives such as cpumask and nodemask 588------------------------------------------------------- 589 590:: 591 592 %*pb 0779 593 %*pbl 0,3-6,8-10 594 595For printing bitmap and its derivatives such as cpumask and nodemask, 596%*pb outputs the bitmap with field width as the number of bits and %*pbl 597output the bitmap as range list with field width as the number of bits. 598 599The field width is passed by value, the bitmap is passed by reference. 600Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease 601printing cpumask and nodemask. 602 603Flags bitfields such as page flags and gfp_flags 604-------------------------------------------------------- 605 606:: 607 608 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) 609 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 610 %pGv read|exec|mayread|maywrite|mayexec|denywrite 611 612For printing flags bitfields as a collection of symbolic constants that 613would construct the value. The type of flags is given by the third 614character. Currently supported are: 615 616 - p - [p]age flags, expects value of type (``unsigned long *``) 617 - v - [v]ma_flags, expects value of type (``unsigned long *``) 618 - g - [g]fp_flags, expects value of type (``gfp_t *``) 619 620The flag names and print order depends on the particular type. 621 622Note that this format should not be used directly in the 623:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() 624functions from <trace/events/mmflags.h>. 625 626Passed by reference. 627 628Network device features 629----------------------- 630 631:: 632 633 %pNF 0x000000000000c000 634 635For printing netdev_features_t. 636 637Passed by reference. 638 639V4L2 and DRM FourCC code (pixel format) 640--------------------------------------- 641 642:: 643 644 %p4cc 645 646Print a FourCC code used by V4L2 or DRM, including format endianness and 647its numerical value as hexadecimal. 648 649Passed by reference. 650 651Examples:: 652 653 %p4cc BG12 little-endian (0x32314742) 654 %p4cc Y10 little-endian (0x20303159) 655 %p4cc NV12 big-endian (0xb231564e) 656 657Generic FourCC code 658------------------- 659 660:: 661 %p4c[h[R]lb] gP00 (0x67503030) 662 663Print a generic FourCC code, as both ASCII characters and its numerical 664value as hexadecimal. 665 666The generic FourCC code is always printed in the big-endian format, 667the most significant byte first. This is the opposite of V4L/DRM FourCCs. 668 669The additional ``h``, ``hR``, ``l``, and ``b`` specifiers define what 670endianness is used to load the stored bytes. The data might be interpreted 671using the host, reversed host byte order, little-endian, or big-endian. 672 673Passed by reference. 674 675Examples for a little-endian machine, given &(u32)0x67503030:: 676 677 %p4ch gP00 (0x67503030) 678 %p4chR 00Pg (0x30305067) 679 %p4cl gP00 (0x67503030) 680 %p4cb 00Pg (0x30305067) 681 682Examples for a big-endian machine, given &(u32)0x67503030:: 683 684 %p4ch gP00 (0x67503030) 685 %p4chR 00Pg (0x30305067) 686 %p4cl 00Pg (0x30305067) 687 %p4cb gP00 (0x67503030) 688 689Rust 690---- 691 692:: 693 694 %pA 695 696Only intended to be used from Rust code to format ``core::fmt::Arguments``. 697Do *not* use it from C. 698 699Thanks 700====== 701 702If you add other %p extensions, please extend <lib/tests/printf_kunit.c> 703with one or more test cases, if at all feasible. 704 705Thank you for your cooperation and attention. 706