Documentation/printk-formats.txt

   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                 int                     %d or %x
  17                 unsigned int            %u or %x
  18                 long                    %ld or %lx
  19                 unsigned long           %lu or %lx
  20                 long long               %lld or %llx
  21                 unsigned long long      %llu or %llx
  22                 size_t                  %zu or %zx
  23                 ssize_t                 %zd or %zx
  24                 s32                     %d or %x
  25                 u32                     %u or %x
  26                 s64                     %lld or %llx
  27                 u64                     %llu or %llx
  28
  29 If <type> is dependent on a config option for its size (e.g., ``sector_t``,
  30 ``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
  31 use a format specifier of its largest possible type and explicitly cast to it.
  32
  33 Example::
  34
  35         printk("test: sector number/total blocks: %llu/%llu\n",
  36                 (unsigned long long)sector, (unsigned long long)blockcount);
  37
  38 Reminder: ``sizeof()`` result is of type ``size_t``.
  39
  40 The kernel's printf does not support ``%n``. For obvious reasons, floating
  41 point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
  42 unsupported specifier or length qualifier results in a WARN and early
  43 return from vsnprintf.
  44
  45 Raw pointer value SHOULD be printed with %p. The kernel supports
  46 the following extended format specifiers for pointer types:
  47
  48 Symbols/Function Pointers
  49 =========================
  50
  51 ::
  52
  53         %pF     versatile_init+0x0/0x110
  54         %pf     versatile_init
  55         %pS     versatile_init+0x0/0x110
  56         %pSR    versatile_init+0x9/0x110
  57                 (with __builtin_extract_return_addr() translation)
  58         %ps     versatile_init
  59         %pB     prev_fn_of_versatile_init+0x88/0x88
  60
  61 The ``F`` and ``f`` specifiers are for printing function pointers,
  62 for example, f->func, &gettimeofday. They have the same result as
  63 ``S`` and ``s`` specifiers. But they do an extra conversion on
  64 ia64, ppc64 and parisc64 architectures where the function pointers
  65 are actually function descriptors.
  66
  67 The ``S`` and ``s`` specifiers can be used for printing symbols
  68 from direct addresses, for example, __builtin_return_address(0),
  69 (void *)regs->ip. They result in the symbol name with (``S``) or
  70 without (``s``) offsets. If KALLSYMS are disabled then the symbol
  71 address is printed instead.
  72
  73 The ``B`` specifier results in the symbol name with offsets and should be
  74 used when printing stack backtraces. The specifier takes into
  75 consideration the effect of compiler optimisations which may occur
  76 when tail-call``s are used and marked with the noreturn GCC attribute.
  77
  78 Examples::
  79
  80         printk("Going to call: %pF\n", gettimeofday);
  81         printk("Going to call: %pF\n", p->func);
  82         printk("%s: called from %pS\n", __func__, (void *)_RET_IP_);
  83         printk("%s: called from %pS\n", __func__,
  84                                 (void *)__builtin_return_address(0));
  85         printk("Faulted at %pS\n", (void *)regs->ip);
  86         printk(" %s%pB\n", (reliable ? "" : "? "), (void *)*stack);
  87
  88
  89 Kernel Pointers
  90 ===============
  91
  92 ::
  93
  94         %pK     0x01234567 or 0x0123456789abcdef
  95
  96 For printing kernel pointers which should be hidden from unprivileged
  97 users. The behaviour of ``%pK`` depends on the ``kptr_restrict sysctl`` - see
  98 Documentation/sysctl/kernel.txt for more details.
  99
 100 Struct Resources
 101 ================
 102
 103 ::
 104
 105         %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
 106                 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
 107         %pR     [mem 0x60000000-0x6fffffff pref] or
 108                 [mem 0x0000000060000000-0x000000006fffffff pref]
 109
 110 For printing struct resources. The ``R`` and ``r`` specifiers result in a
 111 printed resource with (``R``) or without (``r``) a decoded flags member.
 112 Passed by reference.
 113
 114 Physical addresses types ``phys_addr_t``
 115 ========================================
 116
 117 ::
 118
 119         %pa[p]  0x01234567 or 0x0123456789abcdef
 120
 121 For printing a ``phys_addr_t`` type (and its derivatives, such as
 122 ``resource_size_t``) which can vary based on build options, regardless of
 123 the width of the CPU data path. Passed by reference.
 124
 125 DMA addresses types ``dma_addr_t``
 126 ==================================
 127
 128 ::
 129
 130         %pad    0x01234567 or 0x0123456789abcdef
 131
 132 For printing a ``dma_addr_t`` type which can vary based on build options,
 133 regardless of the width of the CPU data path. Passed by reference.
 134
 135 Raw buffer as an escaped string
 136 ===============================
 137
 138 ::
 139
 140         %*pE[achnops]
 141
 142 For printing raw buffer as an escaped string. For the following buffer::
 143
 144                 1b 62 20 5c 43 07 22 90 0d 5d
 145
 146 few examples show how the conversion would be done (the result string
 147 without surrounding quotes)::
 148
 149                 %*pE            "\eb \C\a"\220\r]"
 150                 %*pEhp          "\x1bb \C\x07"\x90\x0d]"
 151                 %*pEa           "\e\142\040\\\103\a\042\220\r\135"
 152
 153 The conversion rules are applied according to an optional combination
 154 of flags (see :c:func:`string_escape_mem` kernel documentation for the
 155 details):
 156
 157         - ``a`` - ESCAPE_ANY
 158         - ``c`` - ESCAPE_SPECIAL
 159         - ``h`` - ESCAPE_HEX
 160         - ``n`` - ESCAPE_NULL
 161         - ``o`` - ESCAPE_OCTAL
 162         - ``p`` - ESCAPE_NP
 163         - ``s`` - ESCAPE_SPACE
 164
 165 By default ESCAPE_ANY_NP is used.
 166
 167 ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
 168 printing SSIDs.
 169
 170 If field width is omitted the 1 byte only will be escaped.
 171
 172 Raw buffer as a hex string
 173 ==========================
 174
 175 ::
 176
 177         %*ph    00 01 02  ...  3f
 178         %*phC   00:01:02: ... :3f
 179         %*phD   00-01-02- ... -3f
 180         %*phN   000102 ... 3f
 181
 182 For printing a small buffers (up to 64 bytes long) as a hex string with
 183 certain separator. For the larger buffers consider to use
 184 :c:func:`print_hex_dump`.
 185
 186 MAC/FDDI addresses
 187 ==================
 188
 189 ::
 190
 191         %pM     00:01:02:03:04:05
 192         %pMR    05:04:03:02:01:00
 193         %pMF    00-01-02-03-04-05
 194         %pm     000102030405
 195         %pmR    050403020100
 196
 197 For printing 6-byte MAC/FDDI addresses in hex notation. The ``M`` and ``m``
 198 specifiers result in a printed address with (``M``) or without (``m``) byte
 199 separators. The default byte separator is the colon (``:``).
 200
 201 Where FDDI addresses are concerned the ``F`` specifier can be used after
 202 the ``M`` specifier to use dash (``-``) separators instead of the default
 203 separator.
 204
 205 For Bluetooth addresses the ``R`` specifier shall be used after the ``M``
 206 specifier to use reversed byte order suitable for visual interpretation
 207 of Bluetooth addresses which are in the little endian order.
 208
 209 Passed by reference.
 210
 211 IPv4 addresses
 212 ==============
 213
 214 ::
 215
 216         %pI4    1.2.3.4
 217         %pi4    001.002.003.004
 218         %p[Ii]4[hnbl]
 219
 220 For printing IPv4 dot-separated decimal addresses. The ``I4`` and ``i4``
 221 specifiers result in a printed address with (``i4``) or without (``I4``)
 222 leading zeros.
 223
 224 The additional ``h``, ``n``, ``b``, and ``l`` specifiers are used to specify
 225 host, network, big or little endian order addresses respectively. Where
 226 no specifier is provided the default network/big endian order is used.
 227
 228 Passed by reference.
 229
 230 IPv6 addresses
 231 ==============
 232
 233 ::
 234
 235         %pI6    0001:0002:0003:0004:0005:0006:0007:0008
 236         %pi6    00010002000300040005000600070008
 237         %pI6c   1:2:3:4:5:6:7:8
 238
 239 For printing IPv6 network-order 16-bit hex addresses. The ``I6`` and ``i6``
 240 specifiers result in a printed address with (``I6``) or without (``i6``)
 241 colon-separators. Leading zeros are always used.
 242
 243 The additional ``c`` specifier can be used with the ``I`` specifier to
 244 print a compressed IPv6 address as described by
 245 http://tools.ietf.org/html/rfc5952
 246
 247 Passed by reference.
 248
 249 IPv4/IPv6 addresses (generic, with port, flowinfo, scope)
 250 =========================================================
 251
 252 ::
 253
 254         %pIS    1.2.3.4         or 0001:0002:0003:0004:0005:0006:0007:0008
 255         %piS    001.002.003.004 or 00010002000300040005000600070008
 256         %pISc   1.2.3.4         or 1:2:3:4:5:6:7:8
 257         %pISpc  1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345
 258         %p[Ii]S[pfschnbl]
 259
 260 For printing an IP address without the need to distinguish whether it``s
 261 of type AF_INET or AF_INET6, a pointer to a valid ``struct sockaddr``,
 262 specified through ``IS`` or ``iS``, can be passed to this format specifier.
 263
 264 The additional ``p``, ``f``, and ``s`` specifiers are used to specify port
 265 (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ``:`` prefix,
 266 flowinfo a ``/`` and scope a ``%``, each followed by the actual value.
 267
 268 In case of an IPv6 address the compressed IPv6 address as described by
 269 http://tools.ietf.org/html/rfc5952 is being used if the additional
 270 specifier ``c`` is given. The IPv6 address is surrounded by ``[``, ``]`` in
 271 case of additional specifiers ``p``, ``f`` or ``s`` as suggested by
 272 https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
 273
 274 In case of IPv4 addresses, the additional ``h``, ``n``, ``b``, and ``l``
 275 specifiers can be used as well and are ignored in case of an IPv6
 276 address.
 277
 278 Passed by reference.
 279
 280 Further examples::
 281
 282         %pISfc          1.2.3.4         or [1:2:3:4:5:6:7:8]/123456789
 283         %pISsc          1.2.3.4         or [1:2:3:4:5:6:7:8]%1234567890
 284         %pISpfc         1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345/123456789
 285
 286 UUID/GUID addresses
 287 ===================
 288
 289 ::
 290
 291         %pUb    00010203-0405-0607-0809-0a0b0c0d0e0f
 292         %pUB    00010203-0405-0607-0809-0A0B0C0D0E0F
 293         %pUl    03020100-0504-0706-0809-0a0b0c0e0e0f
 294         %pUL    03020100-0504-0706-0809-0A0B0C0E0E0F
 295
 296 For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
 297 'b' and 'B' specifiers are used to specify a little endian order in
 298 lower ('l') or upper case ('L') hex characters - and big endian order
 299 in lower ('b') or upper case ('B') hex characters.
 300
 301 Where no additional specifiers are used the default big endian
 302 order with lower case hex characters will be printed.
 303
 304 Passed by reference.
 305
 306 dentry names
 307 ============
 308
 309 ::
 310
 311         %pd{,2,3,4}
 312         %pD{,2,3,4}
 313
 314 For printing dentry name; if we race with :c:func:`d_move`, the name might be
 315 a mix of old and new ones, but it won't oops.  ``%pd`` dentry is a safer
 316 equivalent of ``%s`` ``dentry->d_name.name`` we used to use, ``%pd<n>`` prints
 317 ``n`` last components.  ``%pD`` does the same thing for struct file.
 318
 319 Passed by reference.
 320
 321 block_device names
 322 ==================
 323
 324 ::
 325
 326         %pg     sda, sda1 or loop0p1
 327
 328 For printing name of block_device pointers.
 329
 330 struct va_format
 331 ================
 332
 333 ::
 334
 335         %pV
 336
 337 For printing struct va_format structures. These contain a format string
 338 and va_list as follows::
 339
 340         struct va_format {
 341                 const char *fmt;
 342                 va_list *va;
 343         };
 344
 345 Implements a "recursive vsnprintf".
 346
 347 Do not use this feature without some mechanism to verify the
 348 correctness of the format string and va_list arguments.
 349
 350 Passed by reference.
 351
 352 kobjects
 353 ========
 354
 355 ::
 356
 357         %pO
 358
 359         Base specifier for kobject based structs. Must be followed with
 360         character for specific type of kobject as listed below:
 361
 362         Device tree nodes:
 363
 364         %pOF[fnpPcCF]
 365
 366         For printing device tree nodes. The optional arguments are:
 367             f device node full_name
 368             n device node name
 369             p device node phandle
 370             P device node path spec (name + @unit)
 371             F device node flags
 372             c major compatible string
 373             C full compatible string
 374         Without any arguments prints full_name (same as %pOFf)
 375         The separator when using multiple arguments is ':'
 376
 377         Examples:
 378
 379         %pOF    /foo/bar@0                      - Node full name
 380         %pOFf   /foo/bar@0                      - Same as above
 381         %pOFfp  /foo/bar@0:10                   - Node full name + phandle
 382         %pOFfcF /foo/bar@0:foo,device:--P-      - Node full name +
 383                                                   major compatible string +
 384                                                   node flags
 385                                                         D - dynamic
 386                                                         d - detached
 387                                                         P - Populated
 388                                                         B - Populated bus
 389
 390         Passed by reference.
 391
 392
 393 struct clk
 394 ==========
 395
 396 ::
 397
 398         %pC     pll1
 399         %pCn    pll1
 400         %pCr    1560000000
 401
 402 For printing struct clk structures. ``%pC`` and ``%pCn`` print the name
 403 (Common Clock Framework) or address (legacy clock framework) of the
 404 structure; ``%pCr`` prints the current clock rate.
 405
 406 Passed by reference.
 407
 408 bitmap and its derivatives such as cpumask and nodemask
 409 =======================================================
 410
 411 ::
 412
 413         %*pb    0779
 414         %*pbl   0,3-6,8-10
 415
 416 For printing bitmap and its derivatives such as cpumask and nodemask,
 417 ``%*pb`` output the bitmap with field width as the number of bits and ``%*pbl``
 418 output the bitmap as range list with field width as the number of bits.
 419
 420 Passed by reference.
 421
 422 Flags bitfields such as page flags, gfp_flags
 423 =============================================
 424
 425 ::
 426
 427         %pGp    referenced|uptodate|lru|active|private
 428         %pGg    GFP_USER|GFP_DMA32|GFP_NOWARN
 429         %pGv    read|exec|mayread|maywrite|mayexec|denywrite
 430
 431 For printing flags bitfields as a collection of symbolic constants that
 432 would construct the value. The type of flags is given by the third
 433 character. Currently supported are [p]age flags, [v]ma_flags (both
 434 expect ``unsigned long *``) and [g]fp_flags (expects ``gfp_t *``). The flag
 435 names and print order depends on the particular type.
 436
 437 Note that this format should not be used directly in :c:func:`TP_printk()` part
 438 of a tracepoint. Instead, use the ``show_*_flags()`` functions from
 439 <trace/events/mmflags.h>.
 440
 441 Passed by reference.
 442
 443 Network device features
 444 =======================
 445
 446 ::
 447
 448         %pNF    0x000000000000c000
 449
 450 For printing netdev_features_t.
 451
 452 Passed by reference.
 453
 454 If you add other ``%p`` extensions, please extend lib/test_printf.c with
 455 one or more test cases, if at all feasible.
 456
 457
 458 Thank you for your cooperation and attention.