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