1What: /dev/kmsg 2Date: Mai 2012 3KernelVersion: 3.5 4Contact: Kay Sievers <kay@vrfy.org> 5Description: 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 next 8 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 Due to the record nature of this interface with a "read all" 60 behavior and the specific positions each seek operation sets, 61 SEEK_CUR is not supported, returning -ESPIPE (invalid seek) to 62 errno whenever requested. 63 64 Other seek operations or offsets are not supported because of 65 the special behavior this device has. The device allows to read 66 or write only whole variable length messages (records) that are 67 stored in a ring buffer. 68 69 Because of the non-standard behavior also the error values are 70 non-standard. -ESPIPE is returned for non-zero offset. -EINVAL 71 is returned for other operations, e.g. SEEK_CUR. This behavior 72 and values are historical and could not be modified without the 73 risk of breaking userspace. 74 75 The output format consists of a prefix carrying the syslog 76 prefix including priority and facility, the 64 bit message 77 sequence number and the monotonic timestamp in microseconds, 78 and a flag field. All fields are separated by a ','. 79 80 Future extensions might add more comma separated values before 81 the terminating ';'. Unknown fields and values should be 82 gracefully ignored. 83 84 The human readable text string starts directly after the ';' 85 and is terminated by a '\n'. Untrusted values derived from 86 hardware or other facilities are printed, therefore 87 all non-printable characters and '\' itself in the log message 88 are escaped by "\x00" C-style hex encoding. 89 90 A line starting with ' ', is a continuation line, adding 91 key/value pairs to the log message, which provide the machine 92 readable context of the message, for reliable processing in 93 userspace. 94 95 Example: 96 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) 97 SUBSYSTEM=acpi 98 DEVICE=+acpi:PNP0A03:00 99 6,339,5140900,-;NET: Registered protocol family 10 100 30,340,5690716,-;udevd[80]: starting version 181 101 102 The DEVICE= key uniquely identifies devices the following way: 103 b12:8 - block dev_t 104 c127:3 - char dev_t 105 n8 - netdev ifindex 106 +sound:card0 - subsystem:devname 107 108 The flags field carries '-' by default. A 'c' indicates a 109 fragment of a line. Note, that these hints about continuation 110 lines are not necessarily correct, and the stream could be 111 interleaved with unrelated messages, but merging the lines in 112 the output usually produces better human readable results. A 113 similar logic is used internally when messages are printed to 114 the console, /proc/kmsg or the syslog() syscall. 115 116 By default, kernel tries to avoid fragments by concatenating 117 when it can and fragments are rare; however, when extended 118 console support is enabled, the in-kernel concatenation is 119 disabled and /dev/kmsg output will contain more fragments. If 120 the log consumer performs concatenation, the end result 121 should be the same. In the future, the in-kernel concatenation 122 may be removed entirely and /dev/kmsg users are recommended to 123 implement fragment handling. 124 125Users: dmesg(1), userspace kernel log consumers 126