650 lines · plain
1=========================================2How to get printk format specifiers right3=========================================4 5.. _printk-specifiers:6 7:Author: Randy Dunlap <rdunlap@infradead.org>8:Author: Andrew Murray <amurray@mpc-data.co.uk>9 10 11Integer types12=============13 14::15 16 If variable is of Type, use printk format specifier:17 ------------------------------------------------------------18 signed char %d or %hhx19 unsigned char %u or %x20 char %u or %x21 short int %d or %hx22 unsigned short int %u or %x23 int %d or %x24 unsigned int %u or %x25 long %ld or %lx26 unsigned long %lu or %lx27 long long %lld or %llx28 unsigned long long %llu or %llx29 size_t %zu or %zx30 ssize_t %zd or %zx31 s8 %d or %hhx32 u8 %u or %x33 s16 %d or %hx34 u16 %u or %x35 s32 %d or %x36 u32 %u or %x37 s64 %lld or %llx38 u64 %llu or %llx39 40 41If <type> is architecture-dependent for its size (e.g., cycles_t, tcflag_t) or42is dependent on a config option for its size (e.g., blk_status_t), use a format43specifier of its largest possible type and explicitly cast to it.44 45Example::46 47 printk("test: latency: %llu cycles\n", (unsigned long long)time);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 any53unsupported specifier or length qualifier results in a WARN and early54return from vsnprintf().55 56Pointer types57=============58 59A raw pointer value may be printed with %p which will hash the address60before printing. The kernel also supports extended specifiers for printing61pointers of different types.62 63Some of the extended specifiers print the data on the given address instead64of printing the address itself. In this case, the following error messages65might be printed instead of the unreachable information::66 67 (null) data on plain NULL address68 (efault) data on invalid address69 (einval) invalid data on a valid address70 71Plain Pointers72--------------73 74::75 76 %p abcdef12 or 00000000abcdef1277 78Pointers printed without a specifier extension (i.e unadorned %p) are79hashed to prevent leaking information about the kernel memory layout. This80has the added benefit of providing a unique identifier. On 64-bit machines81the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it82gathers enough entropy.83 84When possible, use specialised modifiers such as %pS or %pB (described below)85to avoid the need of providing an unhashed address that has to be interpreted86post-hoc. If not possible, and the aim of printing the address is to provide87more information for debugging, use %p and boot the kernel with the88``no_hash_pointers`` parameter during debugging, which will print all %p89addresses unmodified. If you *really* always want the unmodified address, see90%px below.91 92If (and only if) you are printing addresses as a content of a virtual file in93e.g. procfs or sysfs (using e.g. seq_printf(), not printk()) read by a94userspace process, use the %pK modifier described below instead of %p or %px.95 96Error Pointers97--------------98 99::100 101 %pe -ENOSPC102 103For printing error pointers (i.e. a pointer for which IS_ERR() is true)104as a symbolic error name. Error values for which no symbolic name is105known are printed in decimal, while a non-ERR_PTR passed as the106argument to %pe gets treated as ordinary %p.107 108Symbols/Function Pointers109-------------------------110 111::112 113 %pS versatile_init+0x0/0x110114 %ps versatile_init115 %pSR versatile_init+0x9/0x110116 (with __builtin_extract_return_addr() translation)117 %pB prev_fn_of_versatile_init+0x88/0x88118 119 120The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic121format. They result in the symbol name with (S) or without (s)122offsets. If KALLSYMS are disabled then the symbol address is printed instead.123 124The ``B`` specifier results in the symbol name with offsets and should be125used when printing stack backtraces. The specifier takes into126consideration the effect of compiler optimisations which may occur127when tail-calls are used and marked with the noreturn GCC attribute.128 129If the pointer is within a module, the module name and optionally build ID is130printed after the symbol name with an extra ``b`` appended to the end of the131specifier.132 133::134 135 %pS versatile_init+0x0/0x110 [module_name]136 %pSb versatile_init+0x0/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]137 %pSRb versatile_init+0x9/0x110 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]138 (with __builtin_extract_return_addr() translation)139 %pBb prev_fn_of_versatile_init+0x88/0x88 [module_name ed5019fdf5e53be37cb1ba7899292d7e143b259e]140 141Probed Pointers from BPF / tracing142----------------------------------143 144::145 146 %pks kernel string147 %pus user string148 149The ``k`` and ``u`` specifiers are used for printing prior probed memory from150either kernel memory (k) or user memory (u). The subsequent ``s`` specifier151results in printing a string. For direct use in regular vsnprintf() the (k)152and (u) annotation is ignored, however, when used out of BPF's bpf_trace_printk(),153for example, it reads the memory it is pointing to without faulting.154 155Kernel Pointers156---------------157 158::159 160 %pK 01234567 or 0123456789abcdef161 162For printing kernel pointers which should be hidden from unprivileged163users. The behaviour of %pK depends on the kptr_restrict sysctl - see164Documentation/admin-guide/sysctl/kernel.rst for more details.165 166This modifier is *only* intended when producing content of a file read by167userspace from e.g. procfs or sysfs, not for dmesg. Please refer to the168section about %p above for discussion about how to manage hashing pointers169in printk().170 171Unmodified Addresses172--------------------173 174::175 176 %px 01234567 or 0123456789abcdef177 178For printing pointers when you *really* want to print the address. Please179consider whether or not you are leaking sensitive information about the180kernel memory layout before printing pointers with %px. %px is functionally181equivalent to %lx (or %lu). %px is preferred because it is more uniquely182grep'able. If in the future we need to modify the way the kernel handles183printing pointers we will be better equipped to find the call sites.184 185Before using %px, consider if using %p is sufficient together with enabling the186``no_hash_pointers`` kernel parameter during debugging sessions (see the %p187description above). One valid scenario for %px might be printing information188immediately before a panic, which prevents any sensitive information to be189exploited anyway, and with %px there would be no need to reproduce the panic190with no_hash_pointers.191 192Pointer Differences193-------------------194 195::196 197 %td 2560198 %tx a00199 200For printing the pointer differences, use the %t modifier for ptrdiff_t.201 202Example::203 204 printk("test: difference between pointers: %td\n", ptr2 - ptr1);205 206Struct Resources207----------------208 209::210 211 %pr [mem 0x60000000-0x6fffffff flags 0x2200] or212 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]213 %pR [mem 0x60000000-0x6fffffff pref] or214 [mem 0x0000000060000000-0x000000006fffffff pref]215 216For printing struct resources. The ``R`` and ``r`` specifiers result in a217printed resource with (R) or without (r) a decoded flags member.218 219Passed by reference.220 221Physical address types phys_addr_t222----------------------------------223 224::225 226 %pa[p] 0x01234567 or 0x0123456789abcdef227 228For printing a phys_addr_t type (and its derivatives, such as229resource_size_t) which can vary based on build options, regardless of the230width of the CPU data path.231 232Passed by reference.233 234DMA address types dma_addr_t235----------------------------236 237::238 239 %pad 0x01234567 or 0x0123456789abcdef240 241For printing a dma_addr_t type which can vary based on build options,242regardless of the width of the CPU data path.243 244Passed by reference.245 246Raw buffer as an escaped string247-------------------------------248 249::250 251 %*pE[achnops]252 253For printing raw buffer as an escaped string. For the following buffer::254 255 1b 62 20 5c 43 07 22 90 0d 5d256 257A few examples show how the conversion would be done (excluding surrounding258quotes)::259 260 %*pE "\eb \C\a"\220\r]"261 %*pEhp "\x1bb \C\x07"\x90\x0d]"262 %*pEa "\e\142\040\\\103\a\042\220\r\135"263 264The conversion rules are applied according to an optional combination265of flags (see :c:func:`string_escape_mem` kernel documentation for the266details):267 268 - a - ESCAPE_ANY269 - c - ESCAPE_SPECIAL270 - h - ESCAPE_HEX271 - n - ESCAPE_NULL272 - o - ESCAPE_OCTAL273 - p - ESCAPE_NP274 - s - ESCAPE_SPACE275 276By default ESCAPE_ANY_NP is used.277 278ESCAPE_ANY_NP is the sane choice for many cases, in particularly for279printing SSIDs.280 281If field width is omitted then 1 byte only will be escaped.282 283Raw buffer as a hex string284--------------------------285 286::287 288 %*ph 00 01 02 ... 3f289 %*phC 00:01:02: ... :3f290 %*phD 00-01-02- ... -3f291 %*phN 000102 ... 3f292 293For printing small buffers (up to 64 bytes long) as a hex string with a294certain separator. For larger buffers consider using295:c:func:`print_hex_dump`.296 297MAC/FDDI addresses298------------------299 300::301 302 %pM 00:01:02:03:04:05303 %pMR 05:04:03:02:01:00304 %pMF 00-01-02-03-04-05305 %pm 000102030405306 %pmR 050403020100307 308For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``309specifiers result in a printed address with (M) or without (m) byte310separators. The default byte separator is the colon (:).311 312Where FDDI addresses are concerned the ``F`` specifier can be used after313the ``M`` specifier to use dash (-) separators instead of the default314separator.315 316For Bluetooth addresses the ``R`` specifier shall be used after the ``M``317specifier to use reversed byte order suitable for visual interpretation318of Bluetooth addresses which are in the little endian order.319 320Passed by reference.321 322IPv4 addresses323--------------324 325::326 327 %pI4 1.2.3.4328 %pi4 001.002.003.004329 %p[Ii]4[hnbl]330 331For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``332specifiers result in a printed address with (i4) or without (I4) leading333zeros.334 335The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify336host, network, big or little endian order addresses respectively. Where337no specifier is provided the default network/big endian order is used.338 339Passed by reference.340 341IPv6 addresses342--------------343 344::345 346 %pI6 0001:0002:0003:0004:0005:0006:0007:0008347 %pi6 00010002000300040005000600070008348 %pI6c 1:2:3:4:5:6:7:8349 350For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``351specifiers result in a printed address with (I6) or without (i6)352colon-separators. Leading zeros are always used.353 354The additional ``c`` specifier can be used with the ``I`` specifier to355print a compressed IPv6 address as described by356https://tools.ietf.org/html/rfc5952357 358Passed by reference.359 360IPv4/IPv6 addresses (generic, with port, flowinfo, scope)361---------------------------------------------------------362 363::364 365 %pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008366 %piS 001.002.003.004 or 00010002000300040005000600070008367 %pISc 1.2.3.4 or 1:2:3:4:5:6:7:8368 %pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345369 %p[Ii]S[pfschnbl]370 371For printing an IP address without the need to distinguish whether it's of372type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,373specified through ``IS`` or ``iS``, can be passed to this format specifier.374 375The additional ``p``, ``f``, and ``s`` specifiers are used to specify port376(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,377flowinfo a ``/`` and scope a ``%``, each followed by the actual value.378 379In case of an IPv6 address the compressed IPv6 address as described by380https://tools.ietf.org/html/rfc5952 is being used if the additional381specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in382case of additional specifiers ``p``, ``f`` or ``s`` as suggested by383https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07384 385In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``386specifiers can be used as well and are ignored in case of an IPv6387address.388 389Passed by reference.390 391Further examples::392 393 %pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789394 %pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890395 %pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789396 397UUID/GUID addresses398-------------------399 400::401 402 %pUb 00010203-0405-0607-0809-0a0b0c0d0e0f403 %pUB 00010203-0405-0607-0809-0A0B0C0D0E0F404 %pUl 03020100-0504-0706-0809-0a0b0c0e0e0f405 %pUL 03020100-0504-0706-0809-0A0B0C0E0E0F406 407For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,408``b`` and ``B`` specifiers are used to specify a little endian order in409lower (l) or upper case (L) hex notation - and big endian order in lower (b)410or upper case (B) hex notation.411 412Where no additional specifiers are used the default big endian413order with lower case hex notation will be printed.414 415Passed by reference.416 417dentry names418------------419 420::421 422 %pd{,2,3,4}423 %pD{,2,3,4}424 425For printing dentry name; if we race with :c:func:`d_move`, the name might426be a mix of old and new ones, but it won't oops. %pd dentry is a safer427equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``428last components. %pD does the same thing for struct file.429 430Passed by reference.431 432block_device names433------------------434 435::436 437 %pg sda, sda1 or loop0p1438 439For printing name of block_device pointers.440 441struct va_format442----------------443 444::445 446 %pV447 448For printing struct va_format structures. These contain a format string449and va_list as follows::450 451 struct va_format {452 const char *fmt;453 va_list *va;454 };455 456Implements a "recursive vsnprintf".457 458Do not use this feature without some mechanism to verify the459correctness of the format string and va_list arguments.460 461Passed by reference.462 463Device tree nodes464-----------------465 466::467 468 %pOF[fnpPcCF]469 470 471For printing device tree node structures. Default behaviour is472equivalent to %pOFf.473 474 - f - device node full_name475 - n - device node name476 - p - device node phandle477 - P - device node path spec (name + @unit)478 - F - device node flags479 - c - major compatible string480 - C - full compatible string481 482The separator when using multiple arguments is ':'483 484Examples::485 486 %pOF /foo/bar@0 - Node full name487 %pOFf /foo/bar@0 - Same as above488 %pOFfp /foo/bar@0:10 - Node full name + phandle489 %pOFfcF /foo/bar@0:foo,device:--P- - Node full name +490 major compatible string +491 node flags492 D - dynamic493 d - detached494 P - Populated495 B - Populated bus496 497Passed by reference.498 499Fwnode handles500--------------501 502::503 504 %pfw[fP]505 506For printing information on fwnode handles. The default is to print the full507node name, including the path. The modifiers are functionally equivalent to508%pOF above.509 510 - f - full name of the node, including the path511 - P - the name of the node including an address (if there is one)512 513Examples (ACPI)::514 515 %pfwf \_SB.PCI0.CIO2.port@1.endpoint@0 - Full node name516 %pfwP endpoint@0 - Node name517 518Examples (OF)::519 520 %pfwf /ocp@68000000/i2c@48072000/camera@10/port/endpoint - Full name521 %pfwP endpoint - Node name522 523Time and date524-------------525 526::527 528 %pt[RT] YYYY-mm-ddTHH:MM:SS529 %pt[RT]s YYYY-mm-dd HH:MM:SS530 %pt[RT]d YYYY-mm-dd531 %pt[RT]t HH:MM:SS532 %pt[RT][dt][r][s]533 534For printing date and time as represented by::535 536 R struct rtc_time structure537 T time64_t type538 539in human readable format.540 541By default year will be incremented by 1900 and month by 1.542Use %pt[RT]r (raw) to suppress this behaviour.543 544The %pt[RT]s (space) will override ISO 8601 separator by using ' ' (space)545instead of 'T' (Capital T) between date and time. It won't have any effect546when date or time is omitted.547 548Passed by reference.549 550struct clk551----------552 553::554 555 %pC pll1556 %pCn pll1557 558For printing struct clk structures. %pC and %pCn print the name of the clock559(Common Clock Framework) or a unique 32-bit ID (legacy clock framework).560 561Passed by reference.562 563bitmap and its derivatives such as cpumask and nodemask564-------------------------------------------------------565 566::567 568 %*pb 0779569 %*pbl 0,3-6,8-10570 571For printing bitmap and its derivatives such as cpumask and nodemask,572%*pb outputs the bitmap with field width as the number of bits and %*pbl573output the bitmap as range list with field width as the number of bits.574 575The field width is passed by value, the bitmap is passed by reference.576Helper macros cpumask_pr_args() and nodemask_pr_args() are available to ease577printing cpumask and nodemask.578 579Flags bitfields such as page flags and gfp_flags580--------------------------------------------------------581 582::583 584 %pGp 0x17ffffc0002036(referenced|uptodate|lru|active|private|node=0|zone=2|lastcpupid=0x1fffff)585 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN586 %pGv read|exec|mayread|maywrite|mayexec|denywrite587 588For printing flags bitfields as a collection of symbolic constants that589would construct the value. The type of flags is given by the third590character. Currently supported are:591 592 - p - [p]age flags, expects value of type (``unsigned long *``)593 - v - [v]ma_flags, expects value of type (``unsigned long *``)594 - g - [g]fp_flags, expects value of type (``gfp_t *``)595 596The flag names and print order depends on the particular type.597 598Note that this format should not be used directly in the599:c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()600functions from <trace/events/mmflags.h>.601 602Passed by reference.603 604Network device features605-----------------------606 607::608 609 %pNF 0x000000000000c000610 611For printing netdev_features_t.612 613Passed by reference.614 615V4L2 and DRM FourCC code (pixel format)616---------------------------------------617 618::619 620 %p4cc621 622Print a FourCC code used by V4L2 or DRM, including format endianness and623its numerical value as hexadecimal.624 625Passed by reference.626 627Examples::628 629 %p4cc BG12 little-endian (0x32314742)630 %p4cc Y10 little-endian (0x20303159)631 %p4cc NV12 big-endian (0xb231564e)632 633Rust634----635 636::637 638 %pA639 640Only intended to be used from Rust code to format ``core::fmt::Arguments``.641Do *not* use it from C.642 643Thanks644======645 646If you add other %p extensions, please extend <lib/test_printf.c> with647one or more test cases, if at all feasible.648 649Thank you for your cooperation and attention.650