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