About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / printk-formats.txt




Custom Search

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

Information is copyright its respective author. All material is available from the Linux Kernel Source distributed under a GPL License. This page is provided as a free service by mjmwired.net.