kmsg - add Documentation/ABI/testing/dev-kmsg

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 higher 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.

		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.

		The values are separated by a ','. Future extensions might

		add more comma separated values before the terminating ';'.

		Unknown 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 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

Users:		dmesg(1), userspace kernel log consumers

		  8 = /dev/random	Nondeterministic random number gen.

		  8 = /dev/random	Nondeterministic random number gen.

		  9 = /dev/urandom	Faster, less secure random number gen.

		  9 = /dev/urandom	Faster, less secure random number gen.

		 10 = /dev/aio		Asynchronous I/O notification interface

		 10 = /dev/aio		Asynchronous I/O notification interface

		 11 = /dev/kmsg		Writes to this come out as printk's

		 11 = /dev/kmsg		Writes to this come out as printk's, reads

					export the buffered printk records.

		 12 = /dev/oldmem	Used by crashdump kernels to access

		 12 = /dev/oldmem	Used by crashdump kernels to access

					the memory of the kernel that crashed.

					the memory of the kernel that crashed.