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