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