0001 What: /dev/kmsg
0002 Date: Mai 2012
0003 KernelVersion: 3.5
0004 Contact: Kay Sievers <kay@vrfy.org>
0005 Description: The /dev/kmsg character device node provides userspace access
0006 to the kernel's printk buffer.
0007
0008 Injecting messages:
0009
0010 Every write() to the opened device node places a log entry in
0011 the kernel's printk buffer.
0012
0013 The logged line can be prefixed with a <N> syslog prefix, which
0014 carries the syslog priority and facility. The single decimal
0015 prefix number is composed of the 3 lowest bits being the syslog
0016 priority and the next 8 bits the syslog facility number.
0017
0018 If no prefix is given, the priority number is the default kernel
0019 log priority and the facility number is set to LOG_USER (1). It
0020 is not possible to inject messages from userspace with the
0021 facility number LOG_KERN (0), to make sure that the origin of
0022 the messages can always be reliably determined.
0023
0024 Accessing the buffer:
0025
0026 Every read() from the opened device node receives one record
0027 of the kernel's printk buffer.
0028
0029 The first read() directly following an open() always returns
0030 first message in the buffer; there is no kernel-internal
0031 persistent state; many readers can concurrently open the device
0032 and read from it, without affecting other readers.
0033
0034 Every read() will receive the next available record. If no more
0035 records are available read() will block, or if O_NONBLOCK is
0036 used -EAGAIN returned.
0037
0038 Messages in the record ring buffer get overwritten as whole,
0039 there are never partial messages received by read().
0040
0041 In case messages get overwritten in the circular buffer while
0042 the device is kept open, the next read() will return -EPIPE,
0043 and the seek position be updated to the next available record.
0044 Subsequent reads() will return available records again.
0045
0046 Unlike the classic syslog() interface, the 64 bit record
0047 sequence numbers allow to calculate the amount of lost
0048 messages, in case the buffer gets overwritten. And they allow
0049 to reconnect to the buffer and reconstruct the read position
0050 if needed, without limiting the interface to a single reader.
0051
0052 The device supports seek with the following parameters:
0053
0054 SEEK_SET, 0
0055 seek to the first entry in the buffer
0056 SEEK_END, 0
0057 seek after the last entry in the buffer
0058 SEEK_DATA, 0
0059 seek after the last record available at the time
0060 the last SYSLOG_ACTION_CLEAR was issued.
0061
0062 Other seek operations or offsets are not supported because of
0063 the special behavior this device has. The device allows to read
0064 or write only whole variable length messages (records) that are
0065 stored in a ring buffer.
0066
0067 Because of the non-standard behavior also the error values are
0068 non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
0069 is returned for other operations, e.g. SEEK_CUR. This behavior
0070 and values are historical and could not be modified without the
0071 risk of breaking userspace.
0072
0073 The output format consists of a prefix carrying the syslog
0074 prefix including priority and facility, the 64 bit message
0075 sequence number and the monotonic timestamp in microseconds,
0076 and a flag field. All fields are separated by a ','.
0077
0078 Future extensions might add more comma separated values before
0079 the terminating ';'. Unknown fields and values should be
0080 gracefully ignored.
0081
0082 The human readable text string starts directly after the ';'
0083 and is terminated by a '\n'. Untrusted values derived from
0084 hardware or other facilities are printed, therefore
0085 all non-printable characters and '\' itself in the log message
0086 are escaped by "\x00" C-style hex encoding.
0087
0088 A line starting with ' ', is a continuation line, adding
0089 key/value pairs to the log message, which provide the machine
0090 readable context of the message, for reliable processing in
0091 userspace.
0092
0093 Example::
0094
0095 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
0096 SUBSYSTEM=acpi
0097 DEVICE=+acpi:PNP0A03:00
0098 6,339,5140900,-;NET: Registered protocol family 10
0099 30,340,5690716,-;udevd[80]: starting version 181
0100
0101 The DEVICE= key uniquely identifies devices the following way:
0102
0103 ============ =================
0104 b12:8 block dev_t
0105 c127:3 char dev_t
0106 n8 netdev ifindex
0107 +sound:card0 subsystem:devname
0108 ============ =================
0109
0110 The flags field carries '-' by default. A 'c' indicates a
0111 fragment of a line. Note, that these hints about continuation
0112 lines are not necessarily correct, and the stream could be
0113 interleaved with unrelated messages, but merging the lines in
0114 the output usually produces better human readable results. A
0115 similar logic is used internally when messages are printed to
0116 the console, /proc/kmsg or the syslog() syscall.
0117
0118 By default, kernel tries to avoid fragments by concatenating
0119 when it can and fragments are rare; however, when extended
0120 console support is enabled, the in-kernel concatenation is
0121 disabled and /dev/kmsg output will contain more fragments. If
0122 the log consumer performs concatenation, the end result
0123 should be the same. In the future, the in-kernel concatenation
0124 may be removed entirely and /dev/kmsg users are recommended to
0125 implement fragment handling.
0126
0127 Users: dmesg(1), userspace kernel log consumers
