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