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