blob: 5962949944fd7307530f26c54c65d783745a8a27 [file] [log] [blame]
Randy Dunlapb67ad182008-11-12 13:26:55 -08001If 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
Geert Uytterhoevene8a7ba52015-04-15 16:17:17 -070011 s32 %d or %x
12 u32 %u or %x
13 s64 %lld or %llx
14 u64 %llu or %llx
15
16If <type> is dependent on a config option for its size (e.g., sector_t,
17blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
18format specifier of its largest possible type and explicitly cast to it.
19Example:
20
21 printk("test: sector number/total blocks: %llu/%llu\n",
22 (unsigned long long)sector, (unsigned long long)blockcount);
23
24Reminder: sizeof() result is of type size_t.
25
Rasmus Villemoesd7ec9a02015-11-06 16:30:35 -080026The kernel's printf does not support %n. For obvious reasons, floating
27point formats (%e, %f, %g, %a) are also not recognized. Use of any
28unsupported specifier or length qualifier results in a WARN and early
29return from vsnprintf.
Randy Dunlapb67ad182008-11-12 13:26:55 -080030
Andrew Murray04c55712011-06-15 12:57:09 -070031Raw pointer value SHOULD be printed with %p. The kernel supports
32the following extended format specifiers for pointer types:
33
34Symbols/Function Pointers:
35
36 %pF versatile_init+0x0/0x110
37 %pf versatile_init
38 %pS versatile_init+0x0/0x110
Joe Perchesb0d33c22012-12-12 10:18:50 -080039 %pSR versatile_init+0x9/0x110
40 (with __builtin_extract_return_addr() translation)
Andrew Murray04c55712011-06-15 12:57:09 -070041 %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
59Kernel 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
67Struct 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.
Geert Uytterhoeven73306602015-04-15 16:17:14 -070076 Passed by reference.
Andrew Murray04c55712011-06-15 12:57:09 -070077
Joe Perchesaaf07622014-01-23 15:54:17 -080078Physical addresses types phys_addr_t:
Stepan Moskovchenko7d799212013-02-21 16:43:09 -080079
Joe Perchesaaf07622014-01-23 15:54:17 -080080 %pa[p] 0x01234567 or 0x0123456789abcdef
Stepan Moskovchenko7d799212013-02-21 16:43:09 -080081
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
Joe Perchesaaf07622014-01-23 15:54:17 -080086DMA 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
Andy Shevchenko71dca952014-10-13 15:55:18 -070093Raw 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
Andy Shevchenko31550a12012-07-30 14:40:27 -0700125Raw buffer as a hex string:
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800126
Andy Shevchenko31550a12012-07-30 14:40:27 -0700127 %*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
Andrew Murray04c55712011-06-15 12:57:09 -0700136MAC/FDDI addresses:
137
138 %pM 00:01:02:03:04:05
Andrei Emeltchenko76597ff92012-07-30 14:40:23 -0700139 %pMR 05:04:03:02:01:00
Andrew Murray04c55712011-06-15 12:57:09 -0700140 %pMF 00-01-02-03-04-05
141 %pm 000102030405
Andy Shevchenko7c591542012-10-04 17:12:33 -0700142 %pmR 050403020100
Andrew Murray04c55712011-06-15 12:57:09 -0700143
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
Andrei Emeltchenko76597ff92012-07-30 14:40:23 -0700152 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
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700156 Passed by reference.
157
Andrew Murray04c55712011-06-15 12:57:09 -0700158IPv4 addresses:
159
160 %pI4 1.2.3.4
161 %pi4 001.002.003.004
Daniel Borkmann8ecada12013-06-28 15:49:39 +0200162 %p[Ii]4[hnbl]
Andrew Murray04c55712011-06-15 12:57:09 -0700163
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
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700172 Passed by reference.
173
Andrew Murray04c55712011-06-15 12:57:09 -0700174IPv6 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
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700188 Passed by reference.
189
Daniel Borkmann10679642013-06-28 19:49:39 +0200190IPv4/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
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700216 Passed by reference.
217
Daniel Borkmann10679642013-06-28 19:49:39 +0200218 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
Andrew Murray04c55712011-06-15 12:57:09 -0700224UUID/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
Rasmus Villemoesd181b712015-02-24 15:26:06 +0100236 Where no additional specifiers are used the default big endian
Andrew Murray04c55712011-06-15 12:57:09 -0700237 order with lower case hex characters will be printed.
238
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700239 Passed by reference.
240
Al Viro4b6ccca2013-09-03 12:00:44 -0400241dentry names:
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800242
Al Viro4b6ccca2013-09-03 12:00:44 -0400243 %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
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700251 Passed by reference.
252
Dmitry Monakhov1031bc52015-04-13 16:31:35 +0400253block_device names:
254
255 %pg sda, sda1 or loop0p1
256
257 For printing name of block_device pointers.
258
Andrew Murray04c55712011-06-15 12:57:09 -0700259struct 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
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800271 Implements a "recursive vsnprintf".
272
Andrew Murray04c55712011-06-15 12:57:09 -0700273 Do not use this feature without some mechanism to verify the
274 correctness of the format string and va_list arguments.
Randy Dunlapb67ad182008-11-12 13:26:55 -0800275
Geert Uytterhoeven73306602015-04-15 16:17:14 -0700276 Passed by reference.
277
Geert Uytterhoeven900cca22015-04-15 16:17:20 -0700278struct 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
Wang Longd0724962015-02-26 03:28:25 +0000290bitmap 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
Linus Torvaldsd6a24d02015-04-18 11:10:49 -0400299 Passed by reference.
Randy Dunlapb67ad182008-11-12 13:26:55 -0800300
Vlastimil Babkaedf14cd2016-03-15 14:55:56 -0700301Flags bitfields such as page flags, gfp_flags:
302
303 %pGp referenced|uptodate|lru|active|private
304 %pGg GFP_USER|GFP_DMA32|GFP_NOWARN
305 %pGv read|exec|mayread|maywrite|mayexec|denywrite
306
307 For printing flags bitfields as a collection of symbolic constants that
308 would construct the value. The type of flags is given by the third
309 character. Currently supported are [p]age flags, [v]ma_flags (both
310 expect unsigned long *) and [g]fp_flags (expects gfp_t *). The flag
311 names and print order depends on the particular type.
312
313 Note that this format should not be used directly in TP_printk() part
314 of a tracepoint. Instead, use the show_*_flags() functions from
315 <trace/events/mmflags.h>.
316
317 Passed by reference.
318
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800319Network device features:
320
321 %pNF 0x000000000000c000
322
323 For printing netdev_features_t.
324
325 Passed by reference.
326
Rasmus Villemoesd7ec9a02015-11-06 16:30:35 -0800327If you add other %p extensions, please extend lib/test_printf.c with
328one or more test cases, if at all feasible.
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800329
Martin Kletzander5e4ee7b2015-11-06 16:30:17 -0800330
Randy Dunlapb67ad182008-11-12 13:26:55 -0800331Thank you for your cooperation and attention.
332
333
Randy Dunlap755727b2013-03-08 12:43:35 -0800334By Randy Dunlap <rdunlap@infradead.org> and
Andrew Murray04c55712011-06-15 12:57:09 -0700335Andrew Murray <amurray@mpc-data.co.uk>