path: root/Documentation/printk-formats.txt (plain)
blob: 54504c5aa047d32992bfe2dc1c2fe12b4e00d67f

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	Pointer Types:
35
36	Pointers printed without a specifier extension (i.e unadorned %p) are
37	hashed to give a unique identifier without leaking kernel addresses to user
38	space. On 64 bit machines the first 32 bits are zeroed. If you _really_
39	want the address see %px below.
40
41	%p abcdef12 or 00000000abcdef12
42
43	Symbols/Function Pointers:
44
45	%pF versatile_init+0x0/0x110
46	%pf versatile_init
47	%pS versatile_init+0x0/0x110
48	%pSR versatile_init+0x9/0x110
49	(with __builtin_extract_return_addr() translation)
50	%ps versatile_init
51	%pB prev_fn_of_versatile_init+0x88/0x88
52
53	For printing symbols and function pointers. The 'S' and 's' specifiers
54	result in the symbol name with ('S') or without ('s') offsets. Where
55	this is used on a kernel without KALLSYMS - the symbol address is
56	printed instead.
57
58	The 'B' specifier results in the symbol name with offsets and should be
59	used when printing stack backtraces. The specifier takes into
60	consideration the effect of compiler optimisations which may occur
61	when tail-call's are used and marked with the noreturn GCC attribute.
62
63	On ia64, ppc64 and parisc64 architectures function pointers are
64	actually function descriptors which must first be resolved. The 'F' and
65	'f' specifiers perform this resolution and then provide the same
66	functionality as the 'S' and 's' specifiers.
67
68	Kernel Pointers:
69
70	%pK 01234567 or 0123456789abcdef
71
72	For printing kernel pointers which should be hidden from unprivileged
73	users. The behaviour of %pK depends on the kptr_restrict sysctl - see
74	Documentation/sysctl/kernel.txt for more details.
75
76	Unmodified Addresses:
77
78	%px 01234567 or 0123456789abcdef
79
80	For printing pointers when you _really_ want to print the address. Please
81	consider whether or not you are leaking sensitive information about the
82	Kernel layout in memory before printing pointers with %px. %px is
83	functionally equivalent to %lx. %px is preferred to %lx because it is more
84	uniquely grep'able. If, in the future, we need to modify the way the Kernel
85	handles printing pointers it will be nice to be able to find the call
86	sites.
87
88	Struct Resources:
89
90	%pr [mem 0x60000000-0x6fffffff flags 0x2200] or
91	[mem 0x0000000060000000-0x000000006fffffff flags 0x2200]
92	%pR [mem 0x60000000-0x6fffffff pref] or
93	[mem 0x0000000060000000-0x000000006fffffff pref]
94
95	For printing struct resources. The 'R' and 'r' specifiers result in a
96	printed resource with ('R') or without ('r') a decoded flags member.
97	Passed by reference.
98
99	Physical addresses types phys_addr_t:
100
101	%pa[p] 0x01234567 or 0x0123456789abcdef
102
103	For printing a phys_addr_t type (and its derivatives, such as
104	resource_size_t) which can vary based on build options, regardless of
105	the width of the CPU data path. Passed by reference.
106
107	DMA addresses types dma_addr_t:
108
109	%pad 0x01234567 or 0x0123456789abcdef
110
111	For printing a dma_addr_t type which can vary based on build options,
112	regardless of the width of the CPU data path. Passed by reference.
113
114	Raw buffer as an escaped string:
115
116	%*pE[achnops]
117
118	For printing raw buffer as an escaped string. For the following buffer
119
120	1b 62 20 5c 43 07 22 90 0d 5d
121
122	few examples show how the conversion would be done (the result string
123	without surrounding quotes):
124
125	%*pE "\eb \C\a"\220\r]"
126	%*pEhp "\x1bb \C\x07"\x90\x0d]"
127	%*pEa "\e\142\040\\\103\a\042\220\r\135"
128
129	The conversion rules are applied according to an optional combination
130	of flags (see string_escape_mem() kernel documentation for the
131	details):
132	a - ESCAPE_ANY
133	c - ESCAPE_SPECIAL
134	h - ESCAPE_HEX
135	n - ESCAPE_NULL
136	o - ESCAPE_OCTAL
137	p - ESCAPE_NP
138	s - ESCAPE_SPACE
139	By default ESCAPE_ANY_NP is used.
140
141	ESCAPE_ANY_NP is the sane choice for many cases, in particularly for
142	printing SSIDs.
143
144	If field width is omitted the 1 byte only will be escaped.
145
146	Raw buffer as a hex string:
147
148	%*ph 00 01 02 ... 3f
149	%*phC 00:01:02: ... :3f
150	%*phD 00-01-02- ... -3f
151	%*phN 000102 ... 3f
152
153	For printing a small buffers (up to 64 bytes long) as a hex string with
154	certain separator. For the larger buffers consider to use
155	print_hex_dump().
156
157	MAC/FDDI addresses:
158
159	%pM 00:01:02:03:04:05
160	%pMR 05:04:03:02:01:00
161	%pMF 00-01-02-03-04-05
162	%pm 000102030405
163	%pmR 050403020100
164
165	For printing 6-byte MAC/FDDI addresses in hex notation. The 'M' and 'm'
166	specifiers result in a printed address with ('M') or without ('m') byte
167	separators. The default byte separator is the colon (':').
168
169	Where FDDI addresses are concerned the 'F' specifier can be used after
170	the 'M' specifier to use dash ('-') separators instead of the default
171	separator.
172
173	For Bluetooth addresses the 'R' specifier shall be used after the 'M'
174	specifier to use reversed byte order suitable for visual interpretation
175	of Bluetooth addresses which are in the little endian order.
176
177	Passed by reference.
178
179	IPv4 addresses:
180
181	%pI4 1.2.3.4
182	%pi4 001.002.003.004
183	%p[Ii]4[hnbl]
184
185	For printing IPv4 dot-separated decimal addresses. The 'I4' and 'i4'
186	specifiers result in a printed address with ('i4') or without ('I4')
187	leading zeros.
188
189	The additional 'h', 'n', 'b', and 'l' specifiers are used to specify
190	host, network, big or little endian order addresses respectively. Where
191	no specifier is provided the default network/big endian order is used.
192
193	Passed by reference.
194
195	IPv6 addresses:
196
197	%pI6 0001:0002:0003:0004:0005:0006:0007:0008
198	%pi6 00010002000300040005000600070008
199	%pI6c 1:2:3:4:5:6:7:8
200
201	For printing IPv6 network-order 16-bit hex addresses. The 'I6' and 'i6'
202	specifiers result in a printed address with ('I6') or without ('i6')
203	colon-separators. Leading zeros are always used.
204
205	The additional 'c' specifier can be used with the 'I' specifier to
206	print a compressed IPv6 address as described by
207	http://tools.ietf.org/html/rfc5952
208
209	Passed by reference.
210
211	IPv4/IPv6 addresses (generic, with port, flowinfo, scope):
212
213	%pIS 1.2.3.4 or 0001:0002:0003:0004:0005:0006:0007:0008
214	%piS 001.002.003.004 or 00010002000300040005000600070008
215	%pISc 1.2.3.4 or 1:2:3:4:5:6:7:8
216	%pISpc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345
217	%p[Ii]S[pfschnbl]
218
219	For printing an IP address without the need to distinguish whether it's
220	of type AF_INET or AF_INET6, a pointer to a valid 'struct sockaddr',
221	specified through 'IS' or 'iS', can be passed to this format specifier.
222
223	The additional 'p', 'f', and 's' specifiers are used to specify port
224	(IPv4, IPv6), flowinfo (IPv6) and scope (IPv6). Ports have a ':' prefix,
225	flowinfo a '/' and scope a '%', each followed by the actual value.
226
227	In case of an IPv6 address the compressed IPv6 address as described by
228	http://tools.ietf.org/html/rfc5952 is being used if the additional
229	specifier 'c' is given. The IPv6 address is surrounded by '[', ']' in
230	case of additional specifiers 'p', 'f' or 's' as suggested by
231	https://tools.ietf.org/html/draft-ietf-6man-text-addr-representation-07
232
233	In case of IPv4 addresses, the additional 'h', 'n', 'b', and 'l'
234	specifiers can be used as well and are ignored in case of an IPv6
235	address.
236
237	Passed by reference.
238
239	Further examples:
240
241	%pISfc 1.2.3.4 or [1:2:3:4:5:6:7:8]/123456789
242	%pISsc 1.2.3.4 or [1:2:3:4:5:6:7:8]%1234567890
243	%pISpfc 1.2.3.4:12345 or [1:2:3:4:5:6:7:8]:12345/123456789
244
245	UUID/GUID addresses:
246
247	%pUb 00010203-0405-0607-0809-0a0b0c0d0e0f
248	%pUB 00010203-0405-0607-0809-0A0B0C0D0E0F
249	%pUl 03020100-0504-0706-0809-0a0b0c0e0e0f
250	%pUL 03020100-0504-0706-0809-0A0B0C0E0E0F
251
252	For printing 16-byte UUID/GUIDs addresses. The additional 'l', 'L',
253	'b' and 'B' specifiers are used to specify a little endian order in
254	lower ('l') or upper case ('L') hex characters - and big endian order
255	in lower ('b') or upper case ('B') hex characters.
256
257	Where no additional specifiers are used the default big endian
258	order with lower case hex characters will be printed.
259
260	Passed by reference.
261
262	dentry names:
263
264	%pd{,2,3,4}
265	%pD{,2,3,4}
266
267	For printing dentry name; if we race with d_move(), the name might be
268	a mix of old and new ones, but it won't oops. %pd dentry is a safer
269	equivalent of %s dentry->d_name.name we used to use, %pd<n> prints
270	n last components. %pD does the same thing for struct file.
271
272	Passed by reference.
273
274	block_device names:
275
276	%pg sda, sda1 or loop0p1
277
278	For printing name of block_device pointers.
279
280	struct va_format:
281
282	%pV
283
284	For printing struct va_format structures. These contain a format string
285	and va_list as follows:
286
287	struct va_format {
288	const char *fmt;
289	va_list *va;
290	};
291
292	Implements a "recursive vsnprintf".
293
294	Do not use this feature without some mechanism to verify the
295	correctness of the format string and va_list arguments.
296
297	Passed by reference.
298
299	struct clk:
300
301	%pC pll1
302	%pCn pll1
303
304	For printing struct clk structures. '%pC' and '%pCn' print the name
305	(Common Clock Framework) or address (legacy clock framework) of the
306	structure.
307
308	Passed by reference.
309
310	bitmap and its derivatives such as cpumask and nodemask:
311
312	%*pb 0779
313	%*pbl 0,3-6,8-10
314
315	For printing bitmap and its derivatives such as cpumask and nodemask,
316	%*pb output the bitmap with field width as the number of bits and %*pbl
317	output the bitmap as range list with field width as the number of bits.
318
319	Passed by reference.
320
321	Flags bitfields such as page flags, gfp_flags:
322
323	%pGp referenced|uptodate|lru|active|private
324	%pGg GFP_USER|GFP_DMA32|GFP_NOWARN
325	%pGv read|exec|mayread|maywrite|mayexec|denywrite
326
327	For printing flags bitfields as a collection of symbolic constants that
328	would construct the value. The type of flags is given by the third
329	character. Currently supported are [p]age flags, [v]ma_flags (both
330	expect unsigned long *) and [g]fp_flags (expects gfp_t *). The flag
331	names and print order depends on the particular type.
332
333	Note that this format should not be used directly in TP_printk() part
334	of a tracepoint. Instead, use the show_*_flags() functions from
335	<trace/events/mmflags.h>.
336
337	Passed by reference.
338
339	Network device features:
340
341	%pNF 0x000000000000c000
342
343	For printing netdev_features_t.
344
345	Passed by reference.
346
347	If you add other %p extensions, please extend lib/test_printf.c with
348	one or more test cases, if at all feasible.
349
350
351	Thank you for your cooperation and attention.
352
353
354	By Randy Dunlap <rdunlap@infradead.org> and
355	Andrew Murray <amurray@mpc-data.co.uk>
356