Documentation/core-api/printk-formats.rst

   1 =========================================
   2 How 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
   9 Integer types
  10 =============
  11
  12 ::
  13
  14         If variable is of Type,         use printk format specifier:
  15         ------------------------------------------------------------
  16                 char                    %hhd or %hhx
  17                 unsigned char           %hhu or %hhx
  18                 short int               %hd or %hx
  19                 unsigned short int      %hu or %hx
  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                      %hhd or %hhx
  29                 u8                      %hhu or %hhx
  30                 s16                     %hd or %hx
  31                 u16                     %hu or %hx
  32                 s32                     %d or %x
  33                 u32                     %u or %x
  34                 s64                     %lld or %llx
  35                 u64                     %llu or %llx
  36
  37
  38 If <type> is dependent on a config option for its size (e.g., sector_t,
  39 blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
  40 format specifier of its largest possible type and explicitly cast to it.
  41
  42 Example::
  43
  44         printk("test: sector number/total blocks: %llu/%llu\n",
  45                 (unsigned long long)sector, (unsigned long long)blockcount);
  46
  47 Reminder: sizeof() returns type size_t.
  48
  49 The 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
  51 unsupported specifier or length qualifier results in a WARN and early
  52 return from vsnprintf().
  53
  54 Pointer types
  55 =============
  56
  57 A raw pointer value may be printed with %p which will hash the address
  58 before printing. The kernel also supports extended specifiers for printing
  59 pointers of different types.
  60
  61 Some of the extended specifiers print the data on the given address instead
  62 of printing the address itself. In this case, the following error messages
  63 might 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
  69 Plain Pointers
  70 --------------
  71
  72 ::
  73
  74         %p      abcdef12 or 00000000abcdef12
  75
  76 Pointers printed without a specifier extension (i.e unadorned %p) are
  77 hashed to prevent leaking information about the kernel memory layout. This
  78 has the added benefit of providing a unique identifier. On 64-bit machines
  79 the first 32 bits are zeroed. The kernel will print ``(ptrval)`` until it
  80 gathers enough entropy. If you *really* want the address see %px below.
  81
  82 Symbols/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
  96 The ``S`` and ``s`` specifiers are used for printing a pointer in symbolic
  97 format. They result in the symbol name with (S) or without (s)
  98 offsets. If KALLSYMS are disabled then the symbol address is printed instead.
  99
 100 Note, that the ``F`` and ``f`` specifiers are identical to ``S`` (``s``)
 101 and thus deprecated. We have ``F`` and ``f`` because on ia64, ppc64 and
 102 parisc64 function pointers are indirect and, in fact, are function
 103 descriptors, which require additional dereferencing before we can lookup
 104 the symbol. As of now, ``S`` and ``s`` perform dereferencing on those
 105 platforms (when needed), so ``F`` and ``f`` exist for compatibility
 106 reasons only.
 107
 108 The ``B`` specifier results in the symbol name with offsets and should be
 109 used when printing stack backtraces. The specifier takes into
 110 consideration the effect of compiler optimisations which may occur
 111 when tail-calls are used and marked with the noreturn GCC attribute.
 112
 113 Kernel Pointers
 114 ---------------
 115
 116 ::
 117
 118         %pK     01234567 or 0123456789abcdef
 119
 120 For printing kernel pointers which should be hidden from unprivileged
 121 users. The behaviour of %pK depends on the kptr_restrict sysctl - see
 122 Documentation/sysctl/kernel.txt for more details.
 123
 124 Unmodified Addresses
 125 --------------------
 126
 127 ::
 128
 129         %px     01234567 or 0123456789abcdef
 130
 131 For printing pointers when you *really* want to print the address. Please
 132 consider whether or not you are leaking sensitive information about the
 133 kernel memory layout before printing pointers with %px. %px is functionally
 134 equivalent to %lx (or %lu). %px is preferred because it is more uniquely
 135 grep'able. If in the future we need to modify the way the kernel handles
 136 printing pointers we will be better equipped to find the call sites.
 137
 138 Struct 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
 148 For printing struct resources. The ``R`` and ``r`` specifiers result in a
 149 printed resource with (R) or without (r) a decoded flags member.
 150
 151 Passed by reference.
 152
 153 Physical address types phys_addr_t
 154 ----------------------------------
 155
 156 ::
 157
 158         %pa[p]  0x01234567 or 0x0123456789abcdef
 159
 160 For printing a phys_addr_t type (and its derivatives, such as
 161 resource_size_t) which can vary based on build options, regardless of the
 162 width of the CPU data path.
 163
 164 Passed by reference.
 165
 166 DMA address types dma_addr_t
 167 ----------------------------
 168
 169 ::
 170
 171         %pad    0x01234567 or 0x0123456789abcdef
 172
 173 For printing a dma_addr_t type which can vary based on build options,
 174 regardless of the width of the CPU data path.
 175
 176 Passed by reference.
 177
 178 Raw buffer as an escaped string
 179 -------------------------------
 180
 181 ::
 182
 183         %*pE[achnops]
 184
 185 For printing raw buffer as an escaped string. For the following buffer::
 186
 187                 1b 62 20 5c 43 07 22 90 0d 5d
 188
 189 A few examples show how the conversion would be done (excluding surrounding
 190 quotes)::
 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
 196 The conversion rules are applied according to an optional combination
 197 of flags (see :c:func:`string_escape_mem` kernel documentation for the
 198 details):
 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
 208 By default ESCAPE_ANY_NP is used.
 209
 210 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
 211 printing SSIDs.
 212
 213 If field width is omitted then 1 byte only will be escaped.
 214
 215 Raw 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
 225 For printing small buffers (up to 64 bytes long) as a hex string with a
 226 certain separator. For larger buffers consider using
 227 :c:func:`print_hex_dump`.
 228
 229 MAC/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
 240 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
 241 specifiers result in a printed address with (M) or without (m) byte
 242 separators. The default byte separator is the colon (:).
 243
 244 Where FDDI addresses are concerned the ``F`` specifier can be used after
 245 the ``M`` specifier to use dash (-) separators instead of the default
 246 separator.
 247
 248 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
 249 specifier to use reversed byte order suitable for visual interpretation
 250 of Bluetooth addresses which are in the little endian order.
 251
 252 Passed by reference.
 253
 254 IPv4 addresses
 255 --------------
 256
 257 ::
 258
 259         %pI4    1.2.3.4
 260         %pi4    001.002.003.004
 261         %p[Ii]4[hnbl]
 262
 263 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
 264 specifiers result in a printed address with (i4) or without (I4) leading
 265 zeros.
 266
 267 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
 268 host, network, big or little endian order addresses respectively. Where
 269 no specifier is provided the default network/big endian order is used.
 270
 271 Passed by reference.
 272
 273 IPv6 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
 282 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
 283 specifiers result in a printed address with (I6) or without (i6)
 284 colon-separators. Leading zeros are always used.
 285
 286 The additional ``c`` specifier can be used with the ``I`` specifier to
 287 print a compressed IPv6 address as described by
 288 http://tools.ietf.org/html/rfc5952
 289
 290 Passed by reference.
 291
 292 IPv4/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
 303 For printing an IP address without the need to distinguish whether it's of
 304 type AF_INET or AF_INET6. A pointer to a valid struct sockaddr,
 305 specified through ``IS`` or ``iS``, can be passed to this format specifier.
 306
 307 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
 308 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
 309 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
 310
 311 In case of an IPv6 address the compressed IPv6 address as described by
 312 http://tools.ietf.org/html/rfc5952 is being used if the additional
 313 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
 314 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
 315 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
 316
 317 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
 318 specifiers can be used as well and are ignored in case of an IPv6
 319 address.
 320
 321 Passed by reference.
 322
 323 Further 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
 329 UUID/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
 339 For printing 16-byte UUID/GUIDs addresses. The additional ``l``, ``L``,
 340 ``b`` and ``B`` specifiers are used to specify a little endian order in
 341 lower (l) or upper case (L) hex notation - and big endian order in lower (b)
 342 or upper case (B) hex notation.
 343
 344 Where no additional specifiers are used the default big endian
 345 order with lower case hex notation will be printed.
 346
 347 Passed by reference.
 348
 349 dentry names
 350 ------------
 351
 352 ::
 353
 354         %pd{,2,3,4}
 355         %pD{,2,3,4}
 356
 357 For printing dentry name; if we race with :c:func:`d_move`, the name might
 358 be a mix of old and new ones, but it won't oops.  %pd dentry is a safer
 359 equivalent of %s dentry->d_name.name we used to use, %pd<n> prints ``n``
 360 last components.  %pD does the same thing for struct file.
 361
 362 Passed by reference.
 363
 364 block_device names
 365 ------------------
 366
 367 ::
 368
 369         %pg     sda, sda1 or loop0p1
 370
 371 For printing name of block_device pointers.
 372
 373 struct va_format
 374 ----------------
 375
 376 ::
 377
 378         %pV
 379
 380 For printing struct va_format structures. These contain a format string
 381 and va_list as follows::
 382
 383         struct va_format {
 384                 const char *fmt;
 385                 va_list *va;
 386         };
 387
 388 Implements a "recursive vsnprintf".
 389
 390 Do not use this feature without some mechanism to verify the
 391 correctness of the format string and va_list arguments.
 392
 393 Passed by reference.
 394
 395 Device tree nodes
 396 -----------------
 397
 398 ::
 399
 400         %pOF[fnpPcCF]
 401
 402
 403 For printing device tree node structures. Default behaviour is
 404 equivalent 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
 414 The separator when using multiple arguments is ':'
 415
 416 Examples::
 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
 429 Passed by reference.
 430
 431 Time 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
 441 For printing date and time as represented by struct rtc_time structure in
 442 human readable format.
 443
 444 By default year will be incremented by 1900 and month by 1. Use %ptRr (raw)
 445 to suppress this behaviour.
 446
 447 Passed by reference.
 448
 449 struct clk
 450 ----------
 451
 452 ::
 453
 454         %pC     pll1
 455         %pCn    pll1
 456
 457 For 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
 460 Passed by reference.
 461
 462 bitmap and its derivatives such as cpumask and nodemask
 463 -------------------------------------------------------
 464
 465 ::
 466
 467         %*pb    0779
 468         %*pbl   0,3-6,8-10
 469
 470 For 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
 472 output the bitmap as range list with field width as the number of bits.
 473
 474 Passed by reference.
 475
 476 Flags 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
 485 For printing flags bitfields as a collection of symbolic constants that
 486 would construct the value. The type of flags is given by the third
 487 character. Currently supported are [p]age flags, [v]ma_flags (both
 488 expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
 489 names and print order depends on the particular type.
 490
 491 Note that this format should not be used directly in the
 492 :c:func:`TP_printk()` part of a tracepoint. Instead, use the show_*_flags()
 493 functions from <trace/events/mmflags.h>.
 494
 495 Passed by reference.
 496
 497 Network device features
 498 -----------------------
 499
 500 ::
 501
 502         %pNF    0x000000000000c000
 503
 504 For printing netdev_features_t.
 505
 506 Passed by reference.
 507
 508 Thanks
 509 ======
 510
 511 If you add other %p extensions, please extend <lib/test_printf.c> with
 512 one or more test cases, if at all feasible.
 513
 514 Thank you for your cooperation and attention.