About Kernel Documentation Linux Kernel Contact Linux Resources Linux Blog

Documentation / ABI / testing / dev-kmsg




Custom Search

Based on kernel version 3.16. Page generated on 2014-08-06 21:35 EST.

1	What:		/dev/kmsg
2	Date:		Mai 2012
3	KernelVersion:	3.5
4	Contact:	Kay Sievers <kay@vrfy.org>
5	Description:	The /dev/kmsg character device node provides userspace access
6			to the kernel's printk buffer.
7	
8			Injecting messages:
9			Every write() to the opened device node places a log entry in
10			the kernel's printk buffer.
11	
12			The logged line can be prefixed with a <N> syslog prefix, which
13			carries the syslog priority and facility. The single decimal
14			prefix number is composed of the 3 lowest bits being the syslog
15			priority and the higher bits the syslog facility number.
16	
17			If no prefix is given, the priority number is the default kernel
18			log priority and the facility number is set to LOG_USER (1). It
19			is not possible to inject messages from userspace with the
20			facility number LOG_KERN (0), to make sure that the origin of
21			the messages can always be reliably determined.
22	
23			Accessing the buffer:
24			Every read() from the opened device node receives one record
25			of the kernel's printk buffer.
26	
27			The first read() directly following an open() always returns
28			first message in the buffer; there is no kernel-internal
29			persistent state; many readers can concurrently open the device
30			and read from it, without affecting other readers.
31	
32			Every read() will receive the next available record. If no more
33			records are available read() will block, or if O_NONBLOCK is
34			used -EAGAIN returned.
35	
36			Messages in the record ring buffer get overwritten as whole,
37			there are never partial messages received by read().
38	
39			In case messages get overwritten in the circular buffer while
40			the device is kept open, the next read() will return -EPIPE,
41			and the seek position be updated to the next available record.
42			Subsequent reads() will return available records again.
43	
44			Unlike the classic syslog() interface, the 64 bit record
45			sequence numbers allow to calculate the amount of lost
46			messages, in case the buffer gets overwritten. And they allow
47			to reconnect to the buffer and reconstruct the read position
48			if needed, without limiting the interface to a single reader.
49	
50			The device supports seek with the following parameters:
51			SEEK_SET, 0
52			  seek to the first entry in the buffer
53			SEEK_END, 0
54			  seek after the last entry in the buffer
55			SEEK_DATA, 0
56			  seek after the last record available at the time
57			  the last SYSLOG_ACTION_CLEAR was issued.
58	
59			The output format consists of a prefix carrying the syslog
60			prefix including priority and facility, the 64 bit message
61			sequence number and the monotonic timestamp in microseconds,
62			and a flag field. All fields are separated by a ','.
63	
64			Future extensions might add more comma separated values before
65			the terminating ';'. Unknown fields and values should be
66			gracefully ignored.
67	
68			The human readable text string starts directly after the ';'
69			and is terminated by a '\n'. Untrusted values derived from
70			hardware or other facilities are printed, therefore
71			all non-printable characters and '\' itself in the log message
72			are escaped by "\x00" C-style hex encoding.
73	
74			A line starting with ' ', is a continuation line, adding
75			key/value pairs to the log message, which provide the machine
76			readable context of the message, for reliable processing in
77			userspace.
78	
79			Example:
80			7,160,424069,-;pci_root PNP0A03:00: host bridge window [io  0x0000-0x0cf7] (ignored)
81			 SUBSYSTEM=acpi
82			 DEVICE=+acpi:PNP0A03:00
83			6,339,5140900,-;NET: Registered protocol family 10
84			30,340,5690716,-;udevd[80]: starting version 181
85	
86			The DEVICE= key uniquely identifies devices the following way:
87			  b12:8        - block dev_t
88			  c127:3       - char dev_t
89			  n8           - netdev ifindex
90			  +sound:card0 - subsystem:devname
91	
92			The flags field carries '-' by default. A 'c' indicates a
93			fragment of a line. All following fragments are flagged with
94			'+'. Note, that these hints about continuation lines are not
95			necessarily correct, and the stream could be interleaved with
96			unrelated messages, but merging the lines in the output
97			usually produces better human readable results. A similar
98			logic is used internally when messages are printed to the
99			console, /proc/kmsg or the syslog() syscall.
100	
101	Users:		dmesg(1), userspace kernel log consumers
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.