Documentation/printk-formats.txt

   1 If variable is of Type,         use printk format specifier:
   2 ---------------------------------------------------------
   3                 int                     %d or %x
   4                 unsigned int            %u or %x
   5                 long                    %ld or %lx
   6                 unsigned long           %lu or %lx
   7                 long long               %lld or %llx
   8                 unsigned long long      %llu or %llx
   9                 size_t                  %zu or %zx
  10                 ssize_t                 %zd or %zx
  11                 s32                     %d or %x
  12                 u32                     %u or %x
  13                 s64                     %lld or %llx
  14                 u64                     %llu or %llx
  15
  16 If <type> is dependent on a config option for its size (e.g., sector_t,
  17 blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
  18 format specifier of its largest possible type and explicitly cast to it.
  19 Example:
  20
  21         printk("test: sector number/total blocks: %llu/%llu\n",
  22                 (unsigned long long)sector, (unsigned long long)blockcount);
  23
  24 Reminder: sizeof() result is of type size_t.
  25
  26 The kernel's printf does not support %n. For obvious reasons, floating
  27 point formats (%e, %f, %g, %a) are also not recognized. Use of any
  28 unsupported specifier or length qualifier results in a WARN and early
  29 return from vsnprintf.
  30
  31 Raw pointer value SHOULD be printed with %p. The kernel supports
  32 the following extended format specifiers for pointer types:
  33
  34 Symbols/Function Pointers:
  35
  36         %pF     versatile_init+0x0/0x110
  37         %pf     versatile_init
  38         %pS     versatile_init+0x0/0x110
  39         %pSR    versatile_init+0x9/0x110
  40                 (with __builtin_extract_return_addr() translation)
  41         %ps     versatile_init
  42         %pB     prev_fn_of_versatile_init+0x88/0x88
  43
  44         For printing symbols and function pointers. The 'S' and 's' specifiers
  45         result in the symbol name with ('S') or without ('s') offsets. Where
  46         this is used on a kernel without KALLSYMS - the symbol address is
  47         printed instead.
  48
  49         The 'B' specifier results in the symbol name with offsets and should be
  50         used when printing stack backtraces. The specifier takes into
  51         consideration the effect of compiler optimisations which may occur
  52         when tail-call's are used and marked with the noreturn GCC attribute.
  53
  54         On ia64, ppc64 and parisc64 architectures function pointers are
  55         actually function descriptors which must first be resolved. The 'F' and
  56         'f' specifiers perform this resolution and then provide the same
  57         functionality as the 'S' and 's' specifiers.
  58
  59 Kernel Pointers:
  60
  61         %pK     0x01234567 or 0x0123456789abcdef
  62
  63         For printing kernel pointers which should be hidden from unprivileged
  64         users. The behaviour of %pK depends on the kptr_restrict sysctl - see
  65         Documentation/sysctl/kernel.txt for more details.
  66
  67 Struct Resources:
  68
  69         %pr     [mem 0x60000000-0x6fffffff flags 0x2200] or
  70                 [mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
  71         %pR     [mem 0x60000000-0x6fffffff pref] or
  72                 [mem 0x0000000060000000-0x000000006fffffff pref]
  73
  74         For printing struct resources. The 'R' and 'r' specifiers result in a
  75         printed resource with ('R') or without ('r') a decoded flags member.
  76         Passed by reference.
  77
  78 Physical addresses types phys_addr_t:
  79
  80         %pa[p]  0x01234567 or 0x0123456789abcdef
  81
  82         For printing a phys_addr_t type (and its derivatives, such as
  83         resource_size_t) which can vary based on build options, regardless of
  84         the width of the CPU data path. Passed by reference.
  85
  86 DMA addresses types dma_addr_t:
  87
  88         %pad    0x01234567 or 0x0123456789abcdef
  89
  90         For printing a dma_addr_t type which can vary based on build options,
  91         regardless of the width of the CPU data path. Passed by reference.
  92
  93 Raw buffer as an escaped string:
  94
  95         %*pE[achnops]
  96
  97         For printing raw buffer as an escaped string. For the following buffer
  98
  99                 1b 62 20 5c 43 07 22 90 0d 5d
 100
 101         few examples show how the conversion would be done (the result string
 102         without surrounding quotes):
 103
 104                 %*pE            "\eb \C\a"\220\r]"
 105                 %*pEhp          "\x1bb \C\x07"\x90\x0d]"
 106                 %*pEa           "\e\142\040\\\103\a\042\220\r\135"
 107
 108         The conversion rules are applied according to an optional combination
 109         of flags (see string_escape_mem() kernel documentation for the
 110         details):
 111                 a - ESCAPE_ANY
 112                 c - ESCAPE_SPECIAL
 113                 h - ESCAPE_HEX
 114                 n - ESCAPE_NULL
 115                 o - ESCAPE_OCTAL
 116                 p - ESCAPE_NP
 117                 s - ESCAPE_SPACE
 118         By default ESCAPE_ANY_NP is used.
 119
 120         ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
 121         printing SSIDs.
 122
 123         If field width is omitted the 1 byte only will be escaped.
 124
 125 Raw buffer as a hex string:
 126
 127         %*ph    00 01 02  ...  3f
 128         %*phC   00:01:02: ... :3f
 129         %*phD   00-01-02- ... -3f
 130         %*phN   000102 ... 3f
 131
 132         For printing a small buffers (up to 64 bytes long) as a hex string with
 133         certain separator. For the larger buffers consider to use
 134         print_hex_dump().
 135
 136 MAC/FDDI addresses:
 137
 138         %pM     00:01:02:03:04:05
 139         %pMR    05:04:03:02:01:00
 140         %pMF    00-01-02-03-04-05
 141         %pm     000102030405
 142         %pmR    050403020100
 143
 144         For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm'
 145         specifiers result in a printed address with ('M') or without ('m') byte
 146         separators. The default byte separator is the colon (':').
 147
 148         Where FDDI addresses are concerned the 'F' specifier can be used after
 149         the 'M' specifier to use dash ('-') separators instead of the default
 150         separator.
 151
 152         For Bluetooth addresses the 'R' specifier shall be used after the 'M'
 153         specifier to use reversed byte order suitable for visual interpretation
 154         of Bluetooth addresses which are in the little endian order.
 155
 156         Passed by reference.
 157
 158 IPv4 addresses:
 159
 160         %pI4    1.2.3.4
 161         %pi4    001.002.003.004
 162         %p[Ii]4[hnbl]
 163
 164         For printing IPv4 dot-separated decimal addresses. The 'I4' and 'i4'
 165         specifiers result in a printed address with ('i4') or without ('I4')
 166         leading zeros.
 167
 168         The additional 'h', 'n', 'b', and 'l' specifiers are used to specify
 169         host, network, big or little endian order addresses respectively. Where
 170         no specifier is provided the default network/big endian order is used.
 171
 172         Passed by reference.
 173
 174 IPv6 addresses:
 175
 176         %pI6    0001:0002:0003:0004:0005:0006:0007:0008
 177         %pi6    00010002000300040005000600070008
 178         %pI6c   1:2:3:4:5:6:7:8
 179
 180         For printing IPv6 network-order 16-bit hex addresses. The 'I6' and 'i6'
 181         specifiers result in a printed address with ('I6') or without ('i6')
 182         colon-separators. Leading zeros are always used.
 183
 184         The additional 'c' specifier can be used with the 'I' specifier to
 185         print a compressed IPv6 address as described by
 186         http://tools.ietf.org/html/rfc5952
 187
 188         Passed by reference.
 189
 190 IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
 191
 192         %pIS    1.2.3.4         or 0001:0002:0003:0004:0005:0006:0007:0008
 193         %piS    001.002.003.004 or 00010002000300040005000600070008
 194         %pISc   1.2.3.4         or 1:2:3:4:5:6:7:8
 195         %pISpc  1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345
 196         %p[Ii]S[pfschnbl]
 197
 198         For printing an IP address without the need to distinguish whether it's
 199         of type AF_INET or AF_INET6, a pointer to a valid 'struct sockaddr',
 200         specified through 'IS' or 'iS', can be passed to this format specifier.
 201
 202         The additional 'p', 'f', and 's' specifiers are used to specify port
 203         (IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ':' prefix,
 204         flowinfo a '/' and scope a '%', each followed by the actual value.
 205
 206         In case of an IPv6 address the compressed IPv6 address as described by
 207         http://tools.ietf.org/html/rfc5952 is being used if the additional
 208         specifier 'c' is given. The IPv6 address is surrounded by '[', ']' in
 209         case of additional specifiers 'p', 'f' or 's' as suggested by
 210         https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
 211
 212         In case of IPv4 addresses, the additional 'h', 'n', 'b', and 'l'
 213         specifiers can be used as well and are ignored in case of an IPv6
 214         address.
 215
 216         Passed by reference.
 217
 218         Further examples:
 219
 220         %pISfc          1.2.3.4         or [1:2:3:4:5:6:7:8]/123456789
 221         %pISsc          1.2.3.4         or [1:2:3:4:5:6:7:8]%1234567890
 222         %pISpfc         1.2.3.4:12345   or [1:2:3:4:5:6:7:8]:12345/123456789
 223
 224 UUID/GUID addresses:
 225
 226         %pUb    00010203-0405-0607-0809-0a0b0c0d0e0f
 227         %pUB    00010203-0405-0607-0809-0A0B0C0D0E0F
 228         %pUl    03020100-0504-0706-0809-0a0b0c0e0e0f
 229         %pUL    03020100-0504-0706-0809-0A0B0C0E0E0F
 230
 231         For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
 232         'b' and 'B' specifiers are used to specify a little endian order in
 233         lower ('l') or upper case ('L') hex characters - and big endian order
 234         in lower ('b') or upper case ('B') hex characters.
 235
 236         Where no additional specifiers are used the default big endian
 237         order with lower case hex characters will be printed.
 238
 239         Passed by reference.
 240
 241 dentry names:
 242
 243         %pd{,2,3,4}
 244         %pD{,2,3,4}
 245
 246         For printing dentry name; if we race with d_move(), the name might be
 247         a mix of old and new ones, but it won't oops.  %pd dentry is a safer
 248         equivalent of %s dentry->d_name.name we used to use, %pd<n> prints
 249         n last components.  %pD does the same thing for struct file.
 250
 251         Passed by reference.
 252
 253 block_device names:
 254
 255         %pg     sda, sda1 or loop0p1
 256
 257         For printing name of block_device pointers.
 258
 259 struct va_format:
 260
 261         %pV
 262
 263         For printing struct va_format structures. These contain a format string
 264         and va_list as follows:
 265
 266         struct va_format {
 267                 const char *fmt;
 268                 va_list *va;
 269         };
 270
 271         Implements a "recursive vsnprintf".
 272
 273         Do not use this feature without some mechanism to verify the
 274         correctness of the format string and va_list arguments.
 275
 276         Passed by reference.
 277
 278 struct clk:
 279
 280         %pC     pll1
 281         %pCn    pll1
 282         %pCr    1560000000
 283
 284         For printing struct clk structures. '%pC' and '%pCn' print the name
 285         (Common Clock Framework) or address (legacy clock framework) of the
 286         structure; '%pCr' prints the current clock rate.
 287
 288         Passed by reference.
 289
 290 bitmap and its derivatives such as cpumask and nodemask:
 291
 292         %*pb    0779
 293         %*pbl   0,3-6,8-10
 294
 295         For printing bitmap and its derivatives such as cpumask and nodemask,
 296         %*pb output the bitmap with field width as the number of bits and %*pbl
 297         output the bitmap as range list with field width as the number of bits.
 298
 299         Passed by reference.
 300
 301 Network device features:
 302
 303         %pNF    0x000000000000c000
 304
 305         For printing netdev_features_t.
 306
 307         Passed by reference.
 308
 309 If you add other %p extensions, please extend lib/test_printf.c with
 310 one or more test cases, if at all feasible.
 311
 312
 313 Thank you for your cooperation and attention.
 314
 315
 316 By Randy Dunlap <rdunlap@infradead.org> and
 317 Andrew Murray <amurray@mpc-data.co.uk>