GNU Linux-libre 4.4.289-gnu1
[releases.git] / 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 struct va_format:
254
255         %pV
256
257         For printing struct va_format structures. These contain a format string
258         and va_list as follows:
259
260         struct va_format {
261                 const char *fmt;
262                 va_list *va;
263         };
264
265         Implements a "recursive vsnprintf".
266
267         Do not use this feature without some mechanism to verify the
268         correctness of the format string and va_list arguments.
269
270         Passed by reference.
271
272 struct clk:
273
274         %pC     pll1
275         %pCn    pll1
276
277         For printing struct clk structures. '%pC' and '%pCn' print the name
278         (Common Clock Framework) or address (legacy clock framework) of the
279         structure.
280
281         Passed by reference.
282
283 bitmap and its derivatives such as cpumask and nodemask:
284
285         %*pb    0779
286         %*pbl   0,3-6,8-10
287
288         For printing bitmap and its derivatives such as cpumask and nodemask,
289         %*pb output the bitmap with field width as the number of bits and %*pbl
290         output the bitmap as range list with field width as the number of bits.
291
292         Passed by reference.
293
294 Network device features:
295
296         %pNF    0x000000000000c000
297
298         For printing netdev_features_t.
299
300         Passed by reference.
301
302 Command from struct task_struct
303
304         %pT     ls
305
306         For printing executable name excluding path from struct
307         task_struct.
308
309         Passed by reference.
310
311 If you add other %p extensions, please extend lib/test_printf.c with
312 one or more test cases, if at all feasible.
313
314
315 Thank you for your cooperation and attention.
316
317
318 By Randy Dunlap <rdunlap@infradead.org> and
319 Andrew Murray <amurray@mpc-data.co.uk>