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
|
