About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / printk-formats.txt


Based on kernel version 4.15. Page generated on 2018-01-29 10:00 EST.

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


About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog