diff options
79 files changed, 6981 insertions, 1310 deletions
diff --git a/Documentation/ABI/testing/dev-kmsg b/Documentation/ABI/testing/dev-kmsg new file mode 100644 index 000000000000..281ecc5f9709 --- /dev/null +++ b/Documentation/ABI/testing/dev-kmsg | |||
| @@ -0,0 +1,90 @@ | |||
| 1 | What: /dev/kmsg | ||
| 2 | Date: Mai 2012 | ||
| 3 | KernelVersion: 3.5 | ||
| 4 | Contact: Kay Sievers <kay@vrfy.org> | ||
| 5 | Description: The /dev/kmsg character device node provides userspace access | ||
| 6 | to the kernel's printk buffer. | ||
| 7 | |||
| 8 | Injecting messages: | ||
| 9 | Every write() to the opened device node places a log entry in | ||
| 10 | the kernel's printk buffer. | ||
| 11 | |||
| 12 | The logged line can be prefixed with a <N> syslog prefix, which | ||
| 13 | carries the syslog priority and facility. The single decimal | ||
| 14 | prefix number is composed of the 3 lowest bits being the syslog | ||
| 15 | priority and the higher bits the syslog facility number. | ||
| 16 | |||
| 17 | If no prefix is given, the priority number is the default kernel | ||
| 18 | log priority and the facility number is set to LOG_USER (1). It | ||
| 19 | is not possible to inject messages from userspace with the | ||
| 20 | facility number LOG_KERN (0), to make sure that the origin of | ||
| 21 | the messages can always be reliably determined. | ||
| 22 | |||
| 23 | Accessing the buffer: | ||
| 24 | Every read() from the opened device node receives one record | ||
| 25 | of the kernel's printk buffer. | ||
| 26 | |||
| 27 | The first read() directly following an open() always returns | ||
| 28 | first message in the buffer; there is no kernel-internal | ||
| 29 | persistent state; many readers can concurrently open the device | ||
| 30 | and read from it, without affecting other readers. | ||
| 31 | |||
| 32 | Every read() will receive the next available record. If no more | ||
| 33 | records are available read() will block, or if O_NONBLOCK is | ||
| 34 | used -EAGAIN returned. | ||
| 35 | |||
| 36 | Messages in the record ring buffer get overwritten as whole, | ||
| 37 | there are never partial messages received by read(). | ||
| 38 | |||
| 39 | In case messages get overwritten in the circular buffer while | ||
| 40 | the device is kept open, the next read() will return -EPIPE, | ||
| 41 | and the seek position be updated to the next available record. | ||
| 42 | Subsequent reads() will return available records again. | ||
| 43 | |||
| 44 | Unlike the classic syslog() interface, the 64 bit record | ||
| 45 | sequence numbers allow to calculate the amount of lost | ||
| 46 | messages, in case the buffer gets overwritten. And they allow | ||
| 47 | to reconnect to the buffer and reconstruct the read position | ||
| 48 | if needed, without limiting the interface to a single reader. | ||
| 49 | |||
| 50 | The device supports seek with the following parameters: | ||
| 51 | SEEK_SET, 0 | ||
| 52 | seek to the first entry in the buffer | ||
| 53 | SEEK_END, 0 | ||
| 54 | seek after the last entry in the buffer | ||
| 55 | SEEK_DATA, 0 | ||
| 56 | seek after the last record available at the time | ||
| 57 | the last SYSLOG_ACTION_CLEAR was issued. | ||
| 58 | |||
| 59 | The output format consists of a prefix carrying the syslog | ||
| 60 | prefix including priority and facility, the 64 bit message | ||
| 61 | sequence number and the monotonic timestamp in microseconds. | ||
| 62 | The values are separated by a ','. Future extensions might | ||
| 63 | add more comma separated values before the terminating ';'. | ||
| 64 | Unknown values should be gracefully ignored. | ||
| 65 | |||
| 66 | The human readable text string starts directly after the ';' | ||
| 67 | and is terminated by a '\n'. Untrusted values derived from | ||
| 68 | hardware or other facilities are printed, therefore | ||
| 69 | all non-printable characters in the log message are escaped | ||
