]>
Commit | Line | Data |
---|---|---|
3b552b92 KS |
1 | What: /dev/kmsg |
2 | Date: Mai 2012 | |
3 | KernelVersion: 3.5 | |
4 | Contact: Kay Sievers <kay@vrfy.org> | |
5 | Description: 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 | |
d39f3d77 KS |
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. | |
3b552b92 KS |
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 | |
d39f3d77 KS |
71 | all non-printable characters and '\' itself in the log message |
72 | are escaped by "\x00" C-style hex encoding. | |
3b552b92 KS |
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: | |
d39f3d77 | 80 | 7,160,424069,-;pci_root PNP0A03:00: host bridge window [io 0x0000-0x0cf7] (ignored) |
3b552b92 KS |
81 | SUBSYSTEM=acpi |
82 | DEVICE=+acpi:PNP0A03:00 | |
d39f3d77 KS |
83 | 6,339,5140900,-;NET: Registered protocol family 10 |
84 | 30,340,5690716,-;udevd[80]: starting version 181 | |
3b552b92 KS |
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 | ||
d39f3d77 KS |
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 | |
4e79162a | 95 | necessarily correct, and the stream could be interleaved with |
d39f3d77 KS |
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 | ||
6fe29354 TH |
101 | By default, kernel tries to avoid fragments by concatenating |
102 | when it can and fragments are rare; however, when extended | |
103 | console support is enabled, the in-kernel concatenation is | |
104 | disabled and /dev/kmsg output will contain more fragments. If | |
105 | the log consumer performs concatenation, the end result | |
106 | should be the same. In the future, the in-kernel concatenation | |
107 | may be removed entirely and /dev/kmsg users are recommended to | |
108 | implement fragment handling. | |
109 | ||
3b552b92 | 110 | Users: dmesg(1), userspace kernel log consumers |