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