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