1SYSLOG(2) Linux Programmer's Manual SYSLOG(2)
2
6 syslog, klogctl - read and/or clear kernel message ring buffer; set
7 console_loglevel
8
10 int syslog(int type, char *bufp, int len);
11 /* No wrapper provided in glibc */
12 /* The glibc interface */
14 #include <sys/klog.h>
15 int klogctl(int type, char *bufp, int len);
17
19 If you need the C library function syslog() (which talks to sys‐
20 logd(8)), then look at syslog(3). The system call of this name is
21 about controlling the kernel printk() buffer, and the glibc wrapper
22 function is called klogctl().
23 The kernel log buffer
25 The kernel has a cyclic buffer of length LOG_BUF_LEN in which messages
26 given as arguments to the kernel function printk() are stored (regard‐
27 less of their loglevel). In early kernels, LOG_BUF_LEN had the value
28 4096; from kernel 1.3.54, it was 8192; from kernel 2.1.113 it was
29 16384; since 2.4.23/2.6 the value is a kernel configuration option
30 (CONFIG_LOG_BUF_SHIFT). In recent kernels the size can be queried with
31 command type 10 (see below).
32 Commands
34 The type argument determines the action taken by this function. The
35 list below specifies the values for type. The symbolic names are
36 defined in the kernel source, but are not exported to user space; you
37 will either need to use the numbers, or define the names yourself.
38 SYSLOG_ACTION_CLOSE (0)
40 Close the log. Currently a NOP.
41 SYSLOG_ACTION_OPEN (1)
43 Open the log. Currently a NOP.
44 SYSLOG_ACTION_READ (2)
46 Read from the log. The call waits until the kernel log buffer
47 is nonempty, and then reads at most len bytes into the buffer
48 pointed to by bufp. The call returns the number of bytes read.
49 Bytes read from the log disappear from the log buffer: the
50 information can be read only once. This is the function exe‐
51 cuted by the kernel when a user program reads /proc/kmsg.
52 SYSLOG_ACTION_READ_ALL (3)
54 Read all messages remaining in the ring buffer, placing then in
55 the buffer pointed to by bufp. The call reads the last len
56 bytes from the log buffer (nondestructively), but will not read
57 more than was written into the buffer since the last "clear ring
58 buffer" command (see command 5 below)). The call returns the
59 number of bytes read.
60 SYSLOG_ACTION_READ_CLEAR (4)
62 Read and clear all messages remaining in the ring buffer. The
63 call does precisely the same as for a type of 3, but also exe‐
64 cutes the "clear ring buffer" command.
65 SYSLOG_ACTION_CLEAR (5)
67 The call executes just the "clear ring buffer" command. The
68 bufp and len arguments are ignored.
69 This command does not really clear the ring buffer. Rather, it
71 sets a kernel bookkeeping variable that determines the results
72 returned by commands 3 (SYSLOG_ACTION_READ_ALL) and 4 (SYS‐
73 LOG_ACTION_READ_CLEAR). This command has no effect on commands
74 2 (SYSLOG_ACTION_READ) and 9 (SYSLOG_ACTION_SIZE_UNREAD).
75 SYSLOG_ACTION_CONSOLE_OFF (6)
77 Disable printk to console. The call sets the console log level
78 to the minimum, so that no messages are printed to the console.
79 The bufp and len arguments are ignored.
80 SYSLOG_ACTION_CONSOLE_ON (7)
82 The call sets the console log level to the default, so that mes‐
83 sages are printed to the console. The bufp and len arguments
84 are ignored.
85 SYSLOG_ACTION_CONSOLE_LEVEL (8)
87 The call sets the console log level to the value given in len,
88 which must be an integer between 1 and 8 (inclusive). See the
89 loglevel section for details. The bufp argument is ignored.
90 SYSLOG_ACTION_SIZE_UNREAD (9) (since Linux 2.4.10)
92 The call returns the number of bytes currently available to be
93 read from the kernel log buffer via command 2 (SYS‐
94 LOG_ACTION_READ). The bufp and len arguments are ignored.
95 SYSLOG_ACTION_SIZE_BUFFER (10) (since Linux 2.6.6)
97 This command returns the total size of the kernel log buffer.
98 The bufp and len arguments are ignored.
99 All commands except 3 and 10 require privilege. In Linux kernels
101 before 2.6.37, command types 3 and 10 are allowed to unprivileged pro‐
102 cesses; since Linux 2.6.37, these commands are allowed to unprivileged
103 processes only if /proc/sys/kernel/dmesg_restrict has the value 0.
104 Before Linux 2.6.37, "privileged" means that the caller has the
105 CAP_SYS_ADMIN capability. Since Linux 2.6.37, "privileged" means that
106 the caller has either the CAP_SYS_ADMIN capability (now deprecated for
107 this purpose) or the (new) CAP_SYSLOG capability.
108 The loglevel
110 The kernel routine printk() will only print a message on the console,
111 if it has a loglevel less than the value of the variable con‐
112 sole_loglevel. This variable initially has the value DEFAULT_CON‐
113 SOLE_LOGLEVEL (7), but is set to 10 if the kernel command line contains
114 the word "debug", and to 15 in case of a kernel fault (the 10 and 15
115 are just silly, and equivalent to 8). This variable is set (to a value
116 in the range 1-8) by a syslog() call with a type of 8. Calls to sys‐
117 log() with type equal to 6 or 7 set the variable to 1 (kernel panics
118 only) or 7 (all except debugging messages), respectively.
119 Every text line in a message has its own loglevel. This level is
121 DEFAULT_MESSAGE_LOGLEVEL - 1 (6) unless the line starts with <d> where
122 d is a digit in the range 1-7, in which case the level is d. The con‐
123 ventional meaning of the loglevel is defined in <linux/kernel.h> as
124 follows:
125 #define KERN_EMERG "<0>" /* system is unusable */
127 #define KERN_ALERT "<1>" /* action must be taken immediately */
128 #define KERN_CRIT "<2>" /* critical conditions */
129 #define KERN_ERR "<3>" /* error conditions */
130 #define KERN_WARNING "<4>" /* warning conditions */
131 #define KERN_NOTICE "<5>" /* normal but significant condition */
132 #define KERN_INFO "<6>" /* informational */
133 #define KERN_DEBUG "<7>" /* debug-level messages */
134
136 For type equal to 2, 3, or 4, a successful call to syslog() returns the
137 number of bytes read. For type 9, syslog() returns the number of bytes
138 currently available to be read on the kernel log buffer. For type 10,
139 syslog() returns the total size of the kernel log buffer. For other
140 values of type, 0 is returned on success.
141 In case of error, -1 is returned, and errno is set to indicate the
143 error.
144
146 EINVAL Bad arguments (e.g., bad type; or for type 2, 3, or 4, buf is
147 NULL, or len is less than zero; or for type 8, the level is out‐
148 side the range 1 to 8).
149 ENOSYS This syslog() system call is not available, because the kernel
151 was compiled with the CONFIG_PRINTK kernel-configuration option
152 disabled.
153 EPERM An attempt was made to change console_loglevel or clear the ker‐
155 nel message ring buffer by a process without sufficient privi‐
156 lege (more precisely: without the CAP_SYS_ADMIN or CAP_SYSLOG
157 capability).
158 ERESTARTSYS
160 System call was interrupted by a signal; nothing was read.
161 (This can be seen only during a trace.)
162
164 This system call is Linux-specific and should not be used in programs
165 intended to be portable.
166
168 From the very start people noted that it is unfortunate that a system
169 call and a library routine of the same name are entirely different ani‐
170 mals.
171
173 syslog(3), capabilities(7)
174
176 This page is part of release 3.53 of the Linux man-pages project. A
177 description of the project, and information about reporting bugs, can
178 be found at http://www.kernel.org/doc/man-pages/.
179Linux 2012-11-29 SYSLOG(2)