| 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, |
| 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. All following fragments are flagged with |
| '+'. 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 |