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 0x0000000060000000-0x000000006fffffff flags 0x2200] 213 %pR [mem 0x60000000-0x6fffffff pref] or 214 [mem 0x0000000060000000-0x000000006fffffff pref] 215 216For printing struct resources. The ``R`` and ``r`` specifiers result in a 217printed resource with (R) or without (r) a decoded flags member. 218 219Passed by reference. 220 221Physical address types phys_addr_t 222---------------------------------- 223 224:: 225 226 %pa[p] 0x01234567 or 0x0123456789abcdef 227 228For printing a phys_addr_t type (and its derivatives, such as 229resource_size_t) which can vary based on build options, regardless of the 230width of the CPU data path. 231 232Passed by reference. 233 234DMA address types dma_addr_t 235---------------------------- 236 237:: 238 239 %pad 0x01234567 or 0x0123456789abcdef 240 241For printing a dma_addr_t type which can vary based on build options, 242regardless of the width of the CPU data path. 243 244Passed by reference. 245 246Raw buffer as an escaped string 247------------------------------- 248 249:: 250 251 %*pE[achnops] 252 253For printing raw buffer as an escaped string. For the following buffer:: 254 255 1b 62 20 5c 43 07 22 90 0d 5d 256 257A few examples show how the conversion would be done (excluding surrounding 258quotes):: 259 260 %*pE "\eb \C\a"\220\r]" 261 %*pEhp "\x1bb \C\x07"\x90\x0d]" 262 %*pEa "\e\142\040\\\103\a\042\220\r\135" 263 264The conversion rules are applied according to an optional combination 265of flags (see :c:func:`string_escape_mem` kernel documentation for the 266details): 267 268 - a - ESCAPE_ANY 269 - c - ESCAPE_SPECIAL 270 - h - ESCAPE_HEX 271 - n - ESCAPE_NULL 272 - o - ESCAPE_OCTAL 273 - p - ESCAPE_NP 274 - s - ESCAPE_SPACE 275 276By default ESCAPE_ANY_NP is used. 277 278ESCAPE_ANY_NP is the sane choice for many cases, in particularly for 279printing SSIDs. 280 281If field width is omitted then 1 byte only will be escaped. 282 283Raw buffer as a hex string 284-------------------------- 285 286:: 287 288 %*ph 00 01 02 ... 3f 289 %*phC 00:01:02: ... :3f 290 %*phD 00-01-02- ... -3f 291 %*phN 000102 ... 3f 292 293For printing small buffers (up to 64 bytes long) as a hex string with a 294certain separator. For larger buffers consider using 295:c:func:`print_hex_dump`. 296 297MAC/FDDI addresses 298------------------ 299 300:: 301 302 %pM 00:01:02:03:04:05 303 %pMR 05:04:03:02:01:00 304 %pMF 00-01-02-03-04-05 305 %pm 000102030405 306 %pmR 050403020100 307 308For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m`` 309specifiers result in a printed address with (M) or without (m) byte 310separators. The default byte separator is the colon (:). 311 312Where FDDI addresses are concerned the ``F`` specifier can be used after 313the ``M`` specifier to use dash (-) separators instead of the default 314separator. 315 316For Bluetooth addresses the ``R`` specifier shall be used after the ``M`` 317specifier to use reversed byte order suitable for visual interpretation 318of Bluetooth addresses which are in the little endian order. 319 320Passed by reference. 321 322IPv4 addresses 323-------------- 324 325:: 326 327 %pI4 1.2.3.4 328 %pi4 001.002.003.004 329 %p[Ii]4[hnbl] 330 331For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4`` 332specifiers result in a printed address with (i4) or without (I4) leading 333zeros. 334 335The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify 336host, network, big or little endian order addresses respectively. Where 337no specifier is provided the default network/big endian order is used. 338 339Passed by reference. 340 341IPv6 addresses 342-------------- 343 344:: 345 346 %pI6 0001:0002:0003:0004:0005:0006:0007:0008 347 %pi6 00010002000300040005000600070008 348 %pI6c 1:2:3:4:5:6:7:8 349 350For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6`` 351specifiers result in a printed address with (I6) or without (i6) 352colon-separators. Leading zeros are always used. 353 354The additional ``c`` specifier can be used with the ``I`` specifier to 355print a compressed IPv6 address as described by 356https://tools.ietf.org/html/rfc5952 357 358Passed by reference. 359 360IPv4/IPv6 addresses (generic, with port, flowinfo, scope) 361--------------------------------------------------------- 362 363:: 364 365 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008 366 %piS 001.002.003.004 or 00010002000300040005000600070008 367 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8 368 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345 369 %p[Ii]S[pfschnbl] 370 371For printing an IP address without the need to distinguish whether it's of 372type AF_INET or AF_INET6. A pointer to a valid struct sockaddr, 373specified through ``IS`` or ``iS``, can be passed to this format specifier. 374 375The additional ``p``, ``f``, and ``s`` specifiers are used to specify port 376(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix, 377flowinfo a ``/`` and scope a ``%``, each followed by the actual value. 378 379In case of an IPv6 address the compressed IPv6 address as described by 380https://tools.ietf.org/html/rfc5952 is being used if the additional 381specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in 382case of additional specifiers ``p``, ``f`` or ``s`` as suggested by 383https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07 384 385In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l`` 386specifiers can be used as well and are ignored in case of an IPv6 387address. 388 389Passed by reference. 390 391Further examples:: 392 393 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789 394 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890 395 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789 396 397UUID/GUID addresses 398------------------- 399 400:: 401 402 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f 403 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F 404 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f 405 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F 406 407For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``, 408``b`` and ``B`` specifiers are used to specify a little endian order in 409lower (l) or upper case (L) hex notation - and big endian order in lower (b) 410or upper case (B) hex notation. 411 412Where no additional specifiers are used the default big endian 413order with lower case hex notation will be printed. 414 415Passed by reference. 416 417dentry names 418------------ 419 420:: 421 422 %pd{,2,3,4} 423 %pD{,2,3,4} 424 425For printing dentry name; if we race with :c:func:`d_move`, the name might 426be a mix of old and new ones, but it won't oops. %pd dentry is a safer 427equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n`` 428last components. %pD does the same thing for struct file. 429 430Passed by reference. 431 432block_device names 433------------------ 434 435:: 436 437 %pg sda, sda1 or loop0p1 438 439For printing name of block_device pointers. 440 441struct va_format 442---------------- 443 444:: 445 446 %pV 447 448For printing struct va_format structures. These contain a format string 449and va_list as follows:: 450 451 struct va_format { 452 const char *fmt; 453 va_list *va; 454 }; 455 456Implements a "recursive vsnprintf". 457 458Do not use this feature without some mechanism to verify the 459correctness of the format string and va_list arguments. 460 461Passed by reference. 462 463Device tree nodes 464----------------- 465 466:: 467 468 %pOF[fnpPcCF] 469 470 471For printing device tree node structures. Default behaviour is 472equivalent to %pOFf. 473 474 - f - device node full_name 475 - n - device node name 476 - p - device node phandle 477 - P - device node path spec (name + @unit) 478 - F - device node flags 479 - c - major compatible string 480 - C - full compatible string 481 482The separator when using multiple arguments is ':' 483 484Examples:: 485 486 %pOF /foo/bar@0 - Node full name 487 %pOFf /foo/bar@0 - Same as above 488 %pOFfp /foo/bar@0:10 - Node full name + phandle 489 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name + 490 major compatible string + 491 node flags 492 D - dynamic 493 d - detached 494 P - Populated 495 B - Populated bus 496 497Passed by reference. 498 499Fwnode handles 500-------------- 501 502:: 503 504 %pfw[fP] 505 506For printing information on fwnode handles. The default is to print the full 507node name, including the path. The modifiers are functionally equivalent to 508%pOF above. 509 510 - f - full name of the node, including the path 511 - P - the name of the node including an address (if there is one) 512 513Examples (ACPI):: 514 515 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name 516 %pfwP endpoint@0 - Node name 517 518Examples (OF):: 519 520 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name 521 %pfwP endpoint - Node name 522 523Time and date 524------------- 525 526:: 527 528 %pt[RT] YYYY-mm-ddTHH:MM:SS 529 %pt[RT]s YYYY-mm-dd HH:MM:SS 530 %pt[RT]d YYYY-mm-dd 531 %pt[RT]t HH:MM:SS 532 %pt[RT][dt][r][s] 533 534For printing date and time as represented by:: 535 536 R struct rtc_time structure 537 T time64_t type 538 539in human readable format. 540 541By default year will be incremented by 1900 and month by 1. 542Use %pt[RT]r (raw) to suppress this behaviour. 543 544The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space) 545instead of 'T' (Capital T) between date and time. It won't have any effect 546when date or time is omitted. 547 548Passed by reference. 549 550struct clk 551---------- 552 553:: 554 555 %pC pll1 556 %pCn pll1 557 558For printing struct clk structures. %pC and %pCn print the name of the clock 559(Common Clock Framework) or a unique 32-bit ID (legacy clock framework). 560 561Passed by reference. 562 563bitmap and its derivatives such as cpumask and nodemask 564------------------------------------------------------- 565 566:: 567 568 %*pb 0779 569 %*pbl 0,3-6,8-10 570 571For printing bitmap and its derivatives such as cpumask and nodemask, 572%*pb outputs the bitmap with field width as the number of bits and %*pbl 573output the bitmap as range list with field width as the number of bits. 574 575The field width is passed by value, the bitmap is passed by reference. 576Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease 577printing cpumask and nodemask. 578 579Flags bitfields such as page flags and gfp_flags 580-------------------------------------------------------- 581 582:: 583 584 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff) 585 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN 586 %pGv read|exec|mayread|maywrite|mayexec|denywrite 587 588For printing flags bitfields as a collection of symbolic constants that 589would construct the value. The type of flags is given by the third 590character. Currently supported are: 591 592 - p - [p]age flags, expects value of type (``unsigned long *``) 593 - v - [v]ma_flags, expects value of type (``unsigned long *``) 594 - g - [g]fp_flags, expects value of type (``gfp_t *``) 595 596The flag names and print order depends on the particular type. 597 598Note that this format should not be used directly in the 599:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags() 600functions from <trace/events/mmflags.h>. 601 602Passed by reference. 603 604Network device features 605----------------------- 606 607:: 608 609 %pNF 0x000000000000c000 610 611For printing netdev_features_t. 612 613Passed by reference. 614 615V4L2 and DRM FourCC code (pixel format) 616--------------------------------------- 617 618:: 619 620 %p4cc 621 622Print a FourCC code used by V4L2 or DRM, including format endianness and 623its numerical value as hexadecimal. 624 625Passed by reference. 626 627Examples:: 628 629 %p4cc BG12 little-endian (0x32314742) 630 %p4cc Y10 little-endian (0x20303159) 631 %p4cc NV12 big-endian (0xb231564e) 632 633Rust 634---- 635 636:: 637 638 %pA 639 640Only intended to be used from Rust code to format ``core::fmt::Arguments``. 641Do *not* use it from C. 642 643Thanks 644====== 645 646If you add other %p extensions, please extend <lib/test_printf.c> with 647one or more test cases, if at all feasible. 648 649Thank you for your cooperation and attention. 650