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