Documentation/ABI/testing/dev-kmsg

Source file repositories/reference/linux-study-clean/Documentation/ABI/testing/dev-kmsg

File Facts

System
Linux kernel
Corpus path
Documentation/ABI/testing/dev-kmsg
Extension
[no extension]
Size
5229 bytes
Lines
128
Domain
Support Tooling And Documentation
Bucket
Documentation
Inferred role
Support Tooling And Documentation: Documentation
Status
atlas-only

Why This File Exists

Repository support layer: documentation, build tooling, samples, user-space helper tools, generated initramfs support, licenses, and validation utilities.

Dependency Surface

Detected Declarations

Annotated Snippet

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

Annotation

Implementation Notes