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 fwnode handles. 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 %pt[RT][dt][r][s] 551 552For printing date and time as represented by:: 553 554 R struct rtc_time structure 555 T time64_t type 556 557in human readable format. 558 559By default year will be incremented by 1900 and month by 1. 560Use %pt[RT]r (raw) to suppress this behaviour. 561 562The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space) 563instead of 'T' (Capital T) between date and time. It won't have any effect 564when date or time is omitted. 565 566Passed by reference. 567 568struct clk 569---------- 570 571:: 572 573 %pC pll1 574 %pCn pll1 575 576For printing struct clk structures. %pC and %pCn print the name of the clock 577(Common Clock Framework) or a unique 32-bit ID (legacy clock framework). 578 579Passed by reference. 580 581bitmap and its derivatives such as cpumask and nodemask 582------------------------------------------------------- 583 584:: 585 586 %*pb 0779 587 %*pbl 0,3-6,8-10 588 589For printing bitmap and its derivatives such as cpumask and nodemask, 590%*pb outputs the bitmap with field width as the number of bits and %*pbl 591output the bitmap as range list with field width as the number of bits. 592 593The field width is passed by value, the bitmap is passed by reference. 594Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease 595printing cpumask and nodemask. 596 597Flags bitfields such as page flags and gfp_flags 598-------------------------------------------------------- 599 600:: 601 602 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) 603 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 604 %pGv read|exec|mayread|maywrite|mayexec|denywrite 605 606For printing flags bitfields as a collection of symbolic constants that 607would construct the value. The type of flags is given by the third 608character. Currently supported are: 609 610 - p - [p]age flags, expects value of type (``unsigned long *``) 611 - v - [v]ma_flags, expects value of type (``unsigned long *``) 612 - g - [g]fp_flags, expects value of type (``gfp_t *``) 613 614The flag names and print order depends on the particular type. 615 616Note that this format should not be used directly in the 617:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() 618functions from <trace/events/mmflags.h>. 619 620Passed by reference. 621 622Network device features 623----------------------- 624 625:: 626 627 %pNF 0x000000000000c000 628 629For printing netdev_features_t. 630 631Passed by reference. 632 633V4L2 and DRM FourCC code (pixel format) 634--------------------------------------- 635 636:: 637 638 %p4cc 639 640Print a FourCC code used by V4L2 or DRM, including format endianness and 641its numerical value as hexadecimal. 642 643Passed by reference. 644 645Examples:: 646 647 %p4cc BG12 little-endian (0x32314742) 648 %p4cc Y10 little-endian (0x20303159) 649 %p4cc NV12 big-endian (0xb231564e) 650 651Rust 652---- 653 654:: 655 656 %pA 657 658Only intended to be used from Rust code to format ``core::fmt::Arguments``. 659Do *not* use it from C. 660 661Thanks 662====== 663 664If you add other %p extensions, please extend <lib/test_printf.c> with 665one or more test cases, if at all feasible. 666 667Thank you for your cooperation and attention. 668