1 What: /dev/kmsg 1 What: /dev/kmsg
2 Date: Mai 2012 2 Date: Mai 2012
3 KernelVersion: 3.5 3 KernelVersion: 3.5
4 Contact: Kay Sievers <kay@vrfy.org> 4 Contact: Kay Sievers <kay@vrfy.org>
5 Description: The /dev/kmsg character device 5 Description: The /dev/kmsg character device node provides userspace access
6 to the kernel's printk buffer. 6 to the kernel's printk buffer.
7 7
8 Injecting messages: 8 Injecting messages:
9 9
10 Every write() to the opened de 10 Every write() to the opened device node places a log entry in
11 the kernel's printk buffer. 11 the kernel's printk buffer.
12 12
13 The logged line can be prefixe 13 The logged line can be prefixed with a <N> syslog prefix, which
14 carries the syslog priority an 14 carries the syslog priority and facility. The single decimal
15 prefix number is composed of t 15 prefix number is composed of the 3 lowest bits being the syslog
16 priority and the next 8 bits t 16 priority and the next 8 bits the syslog facility number.
17 17
18 If no prefix is given, the pri 18 If no prefix is given, the priority number is the default kernel
19 log priority and the facility 19 log priority and the facility number is set to LOG_USER (1). It
20 is not possible to inject mess 20 is not possible to inject messages from userspace with the
21 facility number LOG_KERN (0), 21 facility number LOG_KERN (0), to make sure that the origin of
22 the messages can always be rel 22 the messages can always be reliably determined.
23 23
24 Accessing the buffer: 24 Accessing the buffer:
25 25
26 Every read() from the opened d 26 Every read() from the opened device node receives one record
27 of the kernel's printk buffer. 27 of the kernel's printk buffer.
28 28
29 The first read() directly foll 29 The first read() directly following an open() always returns
30 first message in the buffer; t 30 first message in the buffer; there is no kernel-internal
31 persistent state; many readers 31 persistent state; many readers can concurrently open the device
32 and read from it, without affe 32 and read from it, without affecting other readers.
33 33
34 Every read() will receive the 34 Every read() will receive the next available record. If no more
35 records are available read() w 35 records are available read() will block, or if O_NONBLOCK is
36 used -EAGAIN returned. 36 used -EAGAIN returned.
37 37
38 Messages in the record ring bu 38 Messages in the record ring buffer get overwritten as whole,
39 there are never partial messag 39 there are never partial messages received by read().
40 40
41 In case messages get overwritt 41 In case messages get overwritten in the circular buffer while
42 the device is kept open, the n 42 the device is kept open, the next read() will return -EPIPE,
43 and the seek position be updat 43 and the seek position be updated to the next available record.
44 Subsequent reads() will return 44 Subsequent reads() will return available records again.
45 45
46 Unlike the classic syslog() in 46 Unlike the classic syslog() interface, the 64 bit record
47 sequence numbers allow to calc 47 sequence numbers allow to calculate the amount of lost
48 messages, in case the buffer g 48 messages, in case the buffer gets overwritten. And they allow
49 to reconnect to the buffer and 49 to reconnect to the buffer and reconstruct the read position
50 if needed, without limiting th 50 if needed, without limiting the interface to a single reader.
51 51
52 The device supports seek with 52 The device supports seek with the following parameters:
53 53
54 SEEK_SET, 0 54 SEEK_SET, 0
55 seek to the first entry in t 55 seek to the first entry in the buffer
56 SEEK_END, 0 56 SEEK_END, 0
57 seek after the last entry in 57 seek after the last entry in the buffer
58 SEEK_DATA, 0 58 SEEK_DATA, 0
59 seek after the last record a 59 seek after the last record available at the time
60 the last SYSLOG_ACTION_CLEAR 60 the last SYSLOG_ACTION_CLEAR was issued.
61 61
62 Other seek operations or offse 62 Other seek operations or offsets are not supported because of
63 the special behavior this devi 63 the special behavior this device has. The device allows to read
64 or write only whole variable l 64 or write only whole variable length messages (records) that are
65 stored in a ring buffer. 65 stored in a ring buffer.
66 66
67 Because of the non-standard be 67 Because of the non-standard behavior also the error values are
68 non-standard. -ESPIPE is retur 68 non-standard. -ESPIPE is returned for non-zero offset. -EINVAL
69 is returned for other operatio 69 is returned for other operations, e.g. SEEK_CUR. This behavior
70 and values are historical and 70 and values are historical and could not be modified without the
71 risk of breaking userspace. 71 risk of breaking userspace.
72 72
73 The output format consists of 73 The output format consists of a prefix carrying the syslog
74 prefix including priority and 74 prefix including priority and facility, the 64 bit message
75 sequence number and the monoto 75 sequence number and the monotonic timestamp in microseconds,
76 and a flag field. All fields a 76 and a flag field. All fields are separated by a ','.
77 77
78 Future extensions might add mo 78 Future extensions might add more comma separated values before
79 the terminating ';'. Unknown f 79 the terminating ';'. Unknown fields and values should be
80 gracefully ignored. 80 gracefully ignored.
81 81
82 The human readable text string 82 The human readable text string starts directly after the ';'
83 and is terminated by a '\n'. U 83 and is terminated by a '\n'. Untrusted values derived from
84 hardware or other facilities a 84 hardware or other facilities are printed, therefore
85 all non-printable characters a 85 all non-printable characters and '\' itself in the log message
86 are escaped by "\x00" C-style 86 are escaped by "\x00" C-style hex encoding.
87 87
88 A line starting with ' ', is a 88 A line starting with ' ', is a continuation line, adding
89 key/value pairs to the log mes 89 key/value pairs to the log message, which provide the machine
90 readable context of the messag 90 readable context of the message, for reliable processing in
91 userspace. 91 userspace.
92 92
93 Example:: 93 Example::
94 94
95 7,160,424069,-;pci_root PNP0 95 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored)
96 SUBSYSTEM=acpi 96 SUBSYSTEM=acpi
97 DEVICE=+acpi:PNP0A03:00 97 DEVICE=+acpi:PNP0A03:00
98 6,339,5140900,-;NET: Registe 98 6,339,5140900,-;NET: Registered protocol family 10
99 30,340,5690716,-;udevd[80]: 99 30,340,5690716,-;udevd[80]: starting version 181
100 100
101 The DEVICE= key uniquely ident 101 The DEVICE= key uniquely identifies devices the following way:
102 102
103 ============ ============== 103 ============ =================
104 b12:8 block dev_t 104 b12:8 block dev_t
105 c127:3 char dev_t 105 c127:3 char dev_t
106 n8 netdev ifindex 106 n8 netdev ifindex
107 +sound:card0 subsystem:devn 107 +sound:card0 subsystem:devname
108 ============ ============== 108 ============ =================
109 109
110 The flags field carries '-' by 110 The flags field carries '-' by default. A 'c' indicates a
111 fragment of a line. Note, that 111 fragment of a line. Note, that these hints about continuation
112 lines are not necessarily corr 112 lines are not necessarily correct, and the stream could be
113 interleaved with unrelated mes 113 interleaved with unrelated messages, but merging the lines in
114 the output usually produces be 114 the output usually produces better human readable results. A
115 similar logic is used internal 115 similar logic is used internally when messages are printed to
116 the console, /proc/kmsg or the 116 the console, /proc/kmsg or the syslog() syscall.
117 117
118 By default, kernel tries to av 118 By default, kernel tries to avoid fragments by concatenating
119 when it can and fragments are 119 when it can and fragments are rare; however, when extended
120 console support is enabled, th 120 console support is enabled, the in-kernel concatenation is
121 disabled and /dev/kmsg output 121 disabled and /dev/kmsg output will contain more fragments. If
122 the log consumer performs conc 122 the log consumer performs concatenation, the end result
123 should be the same. In the fut 123 should be the same. In the future, the in-kernel concatenation
124 may be removed entirely and /d 124 may be removed entirely and /dev/kmsg users are recommended to
125 implement fragment handling. 125 implement fragment handling.
126 126
127 Users: dmesg(1), userspace kernel log 127 Users: dmesg(1), userspace kernel log consumers
Linux® is a registered trademark of Linus Torvalds in the United States and other countries.
TOMOYO® is a registered trademark of NTT DATA CORPORATION.