Documentation/ABI/testing/dev-kmsg - linux - Git at Google

 What:		/dev/kmsg
 Date:		Mai 2012
 KernelVersion:	3.5
 Contact:	Kay Sievers <kay@vrfy.org>
 Description:	The /dev/kmsg character device node provides userspace access
 		to the kernel's printk buffer.

 		Injecting messages:
 		Every write() to the opened device node places a log entry in
 		the kernel's printk buffer.

 		The logged line can be prefixed with a <N> syslog prefix, which
 		carries the syslog priority and facility. The single decimal
 		prefix number is composed of the 3 lowest bits being the syslog
 		priority and the next 8 bits the syslog facility number.

 		If no prefix is given, the priority number is the default kernel
 		log priority and the facility number is set to LOG_USER (1). It
 		is not possible to inject messages from userspace with the
 		facility number LOG_KERN (0), to make sure that the origin of
 		the messages can always be reliably determined.

 		Accessing the buffer:
 		Every read() from the opened device node receives one record
 		of the kernel's printk buffer.

 		The first read() directly following an open() always returns
 		first message in the buffer; there is no kernel-internal
 		persistent state; many readers can concurrently open the device
 		and read from it, without affecting other readers.

 		Every read() will receive the next available record. If no more
 		records are available read() will block, or if O_NONBLOCK is
 		used -EAGAIN returned.

 		Messages in the record ring buffer get overwritten as whole,
 		there are never partial messages received by read().

 		In case messages get overwritten in the circular buffer while
 		the device is kept open, the next read() will return -EPIPE,
 		and the seek position be updated to the next available record.
 		Subsequent reads() will return available records again.

 		Unlike the classic syslog() interface, the 64 bit record
 		sequence numbers allow to calculate the amount of lost
 		messages, in case the buffer gets overwritten. And they allow
 		to reconnect to the buffer and reconstruct the read position
 		if needed, without limiting the interface to a single reader.

 		The device supports seek with the following parameters:
 		SEEK_SET, 0
 		  seek to the first entry in the buffer
 		SEEK_END, 0
 		  seek after the last entry in the buffer
 		SEEK_DATA, 0
 		  seek after the last record available at the time
 		  the last SYSLOG_ACTION_CLEAR was issued.

 		Other seek operations or offsets are not supported because of
 		the special behavior this device has. The device allows to read
 		or write only whole variable length messages (records) that are
 		stored in a ring buffer.

 		Because of the non-standard behavior also the error values are
 		non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
 		is returned for other operations, e.g. SEEK_CUR. This behavior
 		and values are historical and could not be modified without the
 		risk of breaking userspace.

 		The output format consists of a prefix carrying the syslog
 		prefix including priority and facility, the 64 bit message
 		sequence number and the monotonic timestamp in microseconds,
 		and a flag field. All fields are separated by a ','.

 		Future extensions might add more comma separated values before
 		the terminating ';'. Unknown fields and values should be
 		gracefully ignored.

 		The human readable text string starts directly after the ';'
 		and is terminated by a '\n'. Untrusted values derived from
 		hardware or other facilities are printed, therefore
 		all non-printable characters and '\' itself in the log message
 		are escaped by "\x00" C-style hex encoding.

 		A line starting with ' ', is a continuation line, adding
 		key/value pairs to the log message, which provide the machine
 		readable context of the message, for reliable processing in
 		userspace.

 		Example:
 		7,160,424069,-;pci_root PNP0A03:00: host bridge window [io  0x0000-0x0cf7] (ignored)
 		 SUBSYSTEM=acpi
 		 DEVICE=+acpi:PNP0A03:00
 		6,339,5140900,-;NET: Registered protocol family 10
 		30,340,5690716,-;udevd[80]: starting version 181

 		The DEVICE= key uniquely identifies devices the following way:
 		  b12:8        - block dev_t
 		  c127:3       - char dev_t
 		  n8           - netdev ifindex
 		  +sound:card0 - subsystem:devname

 		The flags field carries '-' by default. A 'c' indicates a
 		fragment of a line. Note, that these hints about continuation
 		lines are not necessarily correct, and the stream could be
 		interleaved with unrelated messages, but merging the lines in
 		the output usually produces better human readable results. A
 		similar logic is used internally when messages are printed to
 		the console, /proc/kmsg or the syslog() syscall.

 		By default, kernel tries to avoid fragments by concatenating
 		when it can and fragments are rare; however, when extended
 		console support is enabled, the in-kernel concatenation is
 		disabled and /dev/kmsg output will contain more fragments. If
 		the log consumer performs concatenation, the end result
 		should be the same. In the future, the in-kernel concatenation
 		may be removed entirely and /dev/kmsg users are recommended to
 		implement fragment handling.

 Users:		dmesg(1), userspace kernel log consumers
	What: /dev/kmsg
	Date: Mai 2012
	KernelVersion: 3.5
	Contact: Kay Sievers <kay@vrfy.org>
	Description: The /dev/kmsg character device node provides userspace access
	to the kernel's printk buffer.

	Injecting messages:
	Every write() to the opened device node places a log entry in
	the kernel's printk buffer.

	The logged line can be prefixed with a <N> syslog prefix, which
	carries the syslog priority and facility. The single decimal
	prefix number is composed of the 3 lowest bits being the syslog
	priority and the next 8 bits the syslog facility number.

	If no prefix is given, the priority number is the default kernel
	log priority and the facility number is set to LOG_USER (1). It
	is not possible to inject messages from userspace with the
	facility number LOG_KERN (0), to make sure that the origin of
	the messages can always be reliably determined.

	Accessing the buffer:
	Every read() from the opened device node receives one record
	of the kernel's printk buffer.

	The first read() directly following an open() always returns
	first message in the buffer; there is no kernel-internal
	persistent state; many readers can concurrently open the device
	and read from it, without affecting other readers.

	Every read() will receive the next available record. If no more
	records are available read() will block, or if O_NONBLOCK is
	used -EAGAIN returned.

	Messages in the record ring buffer get overwritten as whole,
	there are never partial messages received by read().

	In case messages get overwritten in the circular buffer while
	the device is kept open, the next read() will return -EPIPE,
	and the seek position be updated to the next available record.
	Subsequent reads() will return available records again.

	Unlike the classic syslog() interface, the 64 bit record
	sequence numbers allow to calculate the amount of lost
	messages, in case the buffer gets overwritten. And they allow
	to reconnect to the buffer and reconstruct the read position
	if needed, without limiting the interface to a single reader.

	The device supports seek with the following parameters:
	SEEK_SET, 0
	seek to the first entry in the buffer
	SEEK_END, 0
	seek after the last entry in the buffer
	SEEK_DATA, 0
	seek after the last record available at the time
	the last SYSLOG_ACTION_CLEAR was issued.

	Other seek operations or offsets are not supported because of
	the special behavior this device has. The device allows to read
	or write only whole variable length messages (records) that are
	stored in a ring buffer.

	Because of the non-standard behavior also the error values are
	non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
	is returned for other operations, e.g. SEEK_CUR. This behavior
	and values are historical and could not be modified without the
	risk of breaking userspace.

	The output format consists of a prefix carrying the syslog
	prefix including priority and facility, the 64 bit message
	sequence number and the monotonic timestamp in microseconds,
	and a flag field. All fields are separated by a ','.

	Future extensions might add more comma separated values before
	the terminating ';'. Unknown fields and values should be
	gracefully ignored.

	The human readable text string starts directly after the ';'
	and is terminated by a '\n'. Untrusted values derived from
	hardware or other facilities are printed, therefore
	all non-printable characters and '\' itself in the log message
	are escaped by "\x00" C-style hex encoding.

	A line starting with ' ', is a continuation line, adding
	key/value pairs to the log message, which provide the machine
	readable context of the message, for reliable processing in
	userspace.

	Example:
	7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
	SUBSYSTEM=acpi
	DEVICE=+acpi:PNP0A03:00
	6,339,5140900,-;NET: Registered protocol family 10
	30,340,5690716,-;udevd[80]: starting version 181

	The DEVICE= key uniquely identifies devices the following way:
	b12:8 - block dev_t
	c127:3 - char dev_t
	n8 - netdev ifindex
	+sound:card0 - subsystem:devname

	The flags field carries '-' by default. A 'c' indicates a
	fragment of a line. Note, that these hints about continuation
	lines are not necessarily correct, and the stream could be
	interleaved with unrelated messages, but merging the lines in
	the output usually produces better human readable results. A
	similar logic is used internally when messages are printed to
	the console, /proc/kmsg or the syslog() syscall.

	By default, kernel tries to avoid fragments by concatenating
	when it can and fragments are rare; however, when extended
	console support is enabled, the in-kernel concatenation is
	disabled and /dev/kmsg output will contain more fragments. If
	the log consumer performs concatenation, the end result
	should be the same. In the future, the in-kernel concatenation
	may be removed entirely and /dev/kmsg users are recommended to
	implement fragment handling.

	Users: dmesg(1), userspace kernel log consumers