Documentation/ABI/testing/dev-kmsg

   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
  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
 127 Users:          dmesg(1), userspace kernel log consumers