]>
Commit | Line | Data |
---|---|---|
e32652ca | 1 | '\" t |
fea681da | 2 | .\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) |
ce26c69b | 3 | .\" and Copyright (C) 2012, 2014 Michael Kerrisk <mtk.manpages@gmail.com> |
fea681da | 4 | .\" |
93015253 | 5 | .\" %%%LICENSE_START(VERBATIM) |
fea681da MK |
6 | .\" Permission is granted to make and distribute verbatim copies of this |
7 | .\" manual provided the copyright notice and this permission notice are | |
8 | .\" preserved on all copies. | |
9 | .\" | |
10 | .\" Permission is granted to copy and distribute modified versions of this | |
11 | .\" manual under the conditions for verbatim copying, provided that the | |
12 | .\" entire resulting derived work is distributed under the terms of a | |
13 | .\" permission notice identical to this one. | |
c13182ef | 14 | .\" |
fea681da MK |
15 | .\" Since the Linux kernel and libraries are constantly changing, this |
16 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
17 | .\" responsibility for errors or omissions, or for damages resulting from | |
18 | .\" the use of the information contained herein. The author(s) may not | |
19 | .\" have taken the same level of care in the production of this manual, | |
20 | .\" which is licensed free of charge, as they might when working | |
21 | .\" professionally. | |
c13182ef | 22 | .\" |
fea681da MK |
23 | .\" Formatted or processed versions of this manual, if unaccompanied by |
24 | .\" the source, must acknowledge the copyright and authors of this work. | |
4b72fb64 | 25 | .\" %%%LICENSE_END |
fea681da MK |
26 | .\" |
27 | .\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl> | |
0527015d MK |
28 | .\" 2008-02-15, Jeremy Kerr <jk@ozlabs.org> |
29 | .\" Add info on command type 10; add details on types 6, 7, 8, & 9. | |
30 | .\" 2008-02-15, Michael Kerrisk <mtk.manpages@gmail.com> | |
31 | .\" Update LOG_BUF_LEN details; update RETURN VALUE section. | |
31981fa1 | 32 | .\" |
4b8c67d9 | 33 | .TH SYSLOG 2 2017-09-15 "Linux" "Linux Programmer's Manual" |
fea681da | 34 | .SH NAME |
c13182ef | 35 | syslog, klogctl \- read and/or clear kernel message ring buffer; |
35478399 | 36 | set console_loglevel |
fea681da MK |
37 | .SH SYNOPSIS |
38 | .nf | |
c12fd10d | 39 | .BI "int syslog(int " type ", char *" bufp ", int " len ); |
da8cb51e | 40 | .B " /* No wrapper provided in glibc */" |
68e4db0a | 41 | .PP |
fea681da | 42 | /* The glibc interface */ |
fea681da | 43 | .B "#include <sys/klog.h>" |
68e4db0a | 44 | .PP |
fea681da | 45 | .BI "int klogctl(int " type ", char *" bufp ", int " len ); |
fea681da MK |
46 | .fi |
47 | .SH DESCRIPTION | |
7fdbbd1e MK |
48 | .IR Note : |
49 | Probably, you are looking for the C library function | |
50 | .BR syslog (), | |
51 | which talks to | |
52 | .BR syslogd (8); | |
53 | see | |
54 | .BR syslog (3) | |
55 | for details. | |
efeece04 | 56 | .PP |
7fdbbd1e | 57 | This page describes the kernel |
c12fd10d | 58 | .BR syslog () |
7fdbbd1e | 59 | system call, which is used to control the kernel |
63aa9df0 | 60 | .IR printk () |
7fdbbd1e | 61 | buffer; the glibc wrapper function for the system call is called |
63aa9df0 | 62 | .BR klogctl (). |
1850e19a MK |
63 | .SS The kernel log buffer |
64 | The kernel has a cyclic buffer of length | |
65 | .B LOG_BUF_LEN | |
66 | in which messages given as arguments to the kernel function | |
67 | .BR printk () | |
e530d422 | 68 | are stored (regardless of their log level). |
1850e19a MK |
69 | In early kernels, |
70 | .B LOG_BUF_LEN | |
71 | had the value 4096; | |
72 | from kernel 1.3.54, it was 8192; | |
0e0901c1 MK |
73 | from kernel 2.1.113, it was 16384; |
74 | since kernel 2.4.23/2.6, the value is a kernel configuration option | |
e530d422 MK |
75 | .RB ( CONFIG_LOG_BUF_SHIFT , |
76 | default value dependent on the architecture). | |
1850e19a MK |
77 | .\" Under "General setup" ==> "Kernel log buffer size" |
78 | .\" For 2.6, precisely the option seems to have appeared in 2.5.55. | |
e530d422 | 79 | Since Linux 2.6.6, the size can be queried with command type 10 (see below). |
1850e19a | 80 | .SS Commands |
e4a952a1 MK |
81 | The \fItype\fP argument determines the action taken by this function. |
82 | The list below specifies the values for | |
83 | .IR type . | |
84 | The symbolic names are defined in the kernel source, | |
85 | but are not exported to user space; | |
1850e19a | 86 | you will either need to use the numbers, or define the names yourself. |
e4a952a1 MK |
87 | .TP |
88 | .BR SYSLOG_ACTION_CLOSE " (0)" | |
70a259dc MK |
89 | Close the log. |
90 | Currently a NOP. | |
e4a952a1 MK |
91 | .TP |
92 | .BR SYSLOG_ACTION_OPEN " (1)" | |
70a259dc MK |
93 | Open the log. |
94 | Currently a NOP. | |
e4a952a1 MK |
95 | .TP |
96 | .BR SYSLOG_ACTION_READ " (2)" | |
97 | Read from the log. | |
1850e19a MK |
98 | The call |
99 | waits until the kernel log buffer is nonempty, and then reads | |
100 | at most \fIlen\fP bytes into the buffer pointed to by | |
101 | .IR bufp . | |
102 | The call returns the number of bytes read. | |
103 | Bytes read from the log disappear from the log buffer: | |
33a0ccb2 | 104 | the information can be read only once. |
1850e19a MK |
105 | This is the function executed by the kernel when a user program reads |
106 | .IR /proc/kmsg . | |
e4a952a1 MK |
107 | .TP |
108 | .BR SYSLOG_ACTION_READ_ALL " (3)" | |
55ed5fce | 109 | Read all messages remaining in the ring buffer, |
e530d422 | 110 | placing them in the buffer pointed to by |
55ed5fce | 111 | .IR bufp . |
1850e19a MK |
112 | The call reads the last \fIlen\fP |
113 | bytes from the log buffer (nondestructively), | |
114 | but will not read more than was written into the buffer since the | |
7fc3d058 | 115 | last "clear ring buffer" command (see command 5 below)). |
1850e19a | 116 | The call returns the number of bytes read. |
e4a952a1 MK |
117 | .TP |
118 | .BR SYSLOG_ACTION_READ_CLEAR " (4)" | |
1850e19a MK |
119 | Read and clear all messages remaining in the ring buffer. |
120 | The call does precisely the same as for a | |
121 | .I type | |
122 | of 3, but also executes the "clear ring buffer" command. | |
e4a952a1 MK |
123 | .TP |
124 | .BR SYSLOG_ACTION_CLEAR " (5)" | |
1850e19a MK |
125 | The call executes just the "clear ring buffer" command. |
126 | The | |
127 | .I bufp | |
128 | and | |
129 | .I len | |
130 | arguments are ignored. | |
7fc3d058 MK |
131 | .IP |
132 | This command does not really clear the ring buffer. | |
133 | Rather, it sets a kernel bookkeeping variable that | |
e6d86b41 | 134 | determines the results returned by commands 3 |
7fc3d058 MK |
135 | .RB ( SYSLOG_ACTION_READ_ALL ) |
136 | and 4 | |
137 | .RB ( SYSLOG_ACTION_READ_CLEAR ). | |
138 | This command has no effect on commands 2 | |
139 | .RB ( SYSLOG_ACTION_READ ) | |
140 | and 9 | |
141 | .RB ( SYSLOG_ACTION_SIZE_UNREAD ). | |
e4a952a1 MK |
142 | .TP |
143 | .BR SYSLOG_ACTION_CONSOLE_OFF " (6)" | |
51c9e67e MK |
144 | The command saves the current value of |
145 | .I console_loglevel | |
cbe0e644 | 146 | and then sets |
51c9e67e MK |
147 | .I console_loglevel |
148 | to | |
149 | .IR minimum_console_loglevel , | |
1850e19a | 150 | so that no messages are printed to the console. |
51c9e67e MK |
151 | Before Linux 2.6.32, |
152 | .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 | |
153 | the command simply sets | |
154 | .I console_loglevel | |
155 | to | |
156 | .IR minimum_console_loglevel . | |
e530d422 MK |
157 | See the discussion of |
158 | .IR /proc/sys/kernel/printk , | |
159 | below. | |
efeece04 | 160 | .IP |
1850e19a MK |
161 | The |
162 | .I bufp | |
163 | and | |
164 | .I len | |
165 | arguments are ignored. | |
e4a952a1 MK |
166 | .TP |
167 | .BR SYSLOG_ACTION_CONSOLE_ON " (7)" | |
51c9e67e MK |
168 | If a previous |
169 | .B SYSLOG_ACTION_CONSOLE_OFF | |
170 | command has been performed, | |
171 | this command restores | |
172 | .I console_loglevel | |
173 | to the value that was saved by that command. | |
174 | Before Linux 2.6.32, | |
175 | .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245 | |
176 | this command simply sets | |
177 | .I console_loglevel | |
178 | to | |
179 | .IR default_console_loglevel . | |
e530d422 MK |
180 | See the discussion of |
181 | .IR /proc/sys/kernel/printk , | |
182 | below. | |
efeece04 | 183 | .IP |
1850e19a MK |
184 | The |
185 | .I bufp | |
186 | and | |
187 | .I len | |
188 | arguments are ignored. | |
e4a952a1 MK |
189 | .TP |
190 | .BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)" | |
e530d422 MK |
191 | The call sets |
192 | .I console_loglevel | |
193 | to the value given in | |
1850e19a MK |
194 | .IR len , |
195 | which must be an integer between 1 and 8 (inclusive). | |
e530d422 MK |
196 | The kernel silently enforces a minimum value of |
197 | .IR minimum_console_loglevel | |
198 | for | |
199 | .IR len . | |
1850e19a | 200 | See the |
e530d422 | 201 | .IR "log level" |
1850e19a MK |
202 | section for details. |
203 | The | |
204 | .I bufp | |
205 | argument is ignored. | |
e4a952a1 | 206 | .TP |
1850e19a MK |
207 | .BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)" |
208 | The call | |
209 | returns the number of bytes currently available to be read | |
0adbf43a MK |
210 | from the kernel log buffer via command 2 |
211 | .RB ( SYSLOG_ACTION_READ ). | |
1850e19a MK |
212 | The |
213 | .I bufp | |
214 | and | |
215 | .I len | |
216 | arguments are ignored. | |
e4a952a1 | 217 | .TP |
1850e19a MK |
218 | .BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)" |
219 | This command returns the total size of the kernel log buffer. | |
220 | The | |
221 | .I bufp | |
222 | and | |
223 | .I len | |
224 | arguments are ignored. | |
e4a952a1 | 225 | .PP |
9f924d17 | 226 | All commands except 3 and 10 require privilege. |
dcfe09af | 227 | In Linux kernels before 2.6.37, |
9f924d17 MK |
228 | command types 3 and 10 are allowed to unprivileged processes; |
229 | since Linux 2.6.37, | |
230 | these commands are allowed to unprivileged processes only if | |
dcfe09af MK |
231 | .IR /proc/sys/kernel/dmesg_restrict |
232 | has the value 0. | |
233 | Before Linux 2.6.37, "privileged" means that the caller has the | |
234 | .BR CAP_SYS_ADMIN | |
235 | capability. | |
236 | Since Linux 2.6.37, | |
237 | "privileged" means that the caller has either the | |
238 | .BR CAP_SYS_ADMIN | |
239 | capability (now deprecated for this purpose) or the (new) | |
240 | .BR CAP_SYSLOG | |
241 | capability. | |
e530d422 MK |
242 | .\" |
243 | .\" | |
244 | .SS /proc/sys/kernel/printk | |
245 | .I /proc/sys/kernel/printk | |
246 | is a writable file containing four integer values that influence kernel | |
247 | .I printk() | |
248 | behavior when printing or logging error messages. | |
249 | The four values are: | |
250 | .TP | |
251 | .I console_loglevel | |
252 | Only messages with a log level lower than this value will | |
253 | be printed to the console. | |
254 | The default value for this field is | |
891e1629 | 255 | .B DEFAULT_CONSOLE_LOGLEVEL |
e530d422 MK |
256 | (7), but it is set to |
257 | 4 if the kernel command line contains the word "quiet", \" since Linux 2.4 | |
258 | 10 if the kernel command line contains the word "debug", | |
259 | and to 15 in case | |
e9496f74 | 260 | of a kernel fault (the 10 and 15 are just silly, and equivalent to 8). |
e530d422 MK |
261 | The value of |
262 | .IR console_loglevel | |
d2fdb1e3 | 263 | can be set (to a value in the range 1\(en8) by a |
1850e19a MK |
264 | .BR syslog () |
265 | call with a | |
266 | .I type | |
267 | of 8. | |
e530d422 MK |
268 | .TP |
269 | .I default_message_loglevel | |
270 | This value will be used as the log level for | |
271 | .IR printk() | |
272 | messages that do not have an explicit level. | |
273 | Up to and including Linux 2.6.38, | |
274 | the hard-coded default value for this field was 4 | |
275 | .RB ( KERN_WARNING ); | |
276 | since Linux 2.6.39, | |
277 | .\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5 | |
278 | the default value is a defined by the kernel configuration option | |
279 | .BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL , | |
280 | which defaults to 4. | |
281 | .TP | |
282 | .I minimum_console_loglevel | |
283 | The value in this field is the minimum value to which | |
284 | .I console_loglevel | |
285 | can be set. | |
286 | .TP | |
287 | .I default_console_loglevel | |
288 | This is the default value for | |
289 | .IR console_loglevel . | |
290 | .\" | |
291 | .\" | |
292 | .SS The log level | |
293 | Every | |
294 | .IR printk () | |
295 | message has its own log level. | |
296 | If the log level is not explicitly specified as part of the message, | |
297 | it defaults to | |
298 | .IR default_message_loglevel . | |
299 | The conventional meaning of the log level is as follows: | |
e32652ca MK |
300 | .TS |
301 | lB lB lB | |
302 | lB c l. | |
303 | Kernel constant Level value Meaning | |
304 | KERN_EMERG 0 System is unusable | |
305 | KERN_ALERT 1 Action must be taken immediately | |
306 | KERN_CRIT 2 Critical conditions | |
307 | KERN_ERR 3 Error conditions | |
308 | KERN_WARNING 4 Warning conditions | |
309 | KERN_NOTICE 5 Normal but significant condition | |
310 | KERN_INFO 6 Informational | |
311 | KERN_DEBUG 7 Debug-level messages | |
312 | .TE | |
efeece04 | 313 | .sp 1 |
e530d422 MK |
314 | The kernel |
315 | .IR printk() | |
316 | routine will print a message on the | |
317 | console only if it has a log level less than the value of | |
318 | .IR console_loglevel . | |
47297adb | 319 | .SH RETURN VALUE |
0527015d | 320 | For \fItype\fP equal to 2, 3, or 4, a successful call to |
60a90ecd MK |
321 | .BR syslog () |
322 | returns the number | |
0527015d MK |
323 | of bytes read. |
324 | For \fItype\fP 9, | |
325 | .BR syslog () | |
326 | returns the number of bytes currently | |
327 | available to be read on the kernel log buffer. | |
328 | For \fItype\fP 10, | |
329 | .BR syslog () | |
84a275c4 | 330 | returns the total size of the kernel log buffer. |
0527015d | 331 | For other values of \fItype\fP, 0 is returned on success. |
efeece04 | 332 | .PP |
0527015d MK |
333 | In case of error, \-1 is returned, |
334 | and \fIerrno\fP is set to indicate the error. | |
fea681da MK |
335 | .SH ERRORS |
336 | .TP | |
337 | .B EINVAL | |
c4bb193f | 338 | Bad arguments (e.g., |
0527015d MK |
339 | bad |
340 | .IR type ; | |
341 | or for | |
342 | .I type | |
343 | 2, 3, or 4, | |
344 | .I buf | |
345 | is NULL, | |
346 | or | |
347 | .I len | |
348 | is less than zero; or for | |
349 | .I type | |
350 | 8, the | |
351 | .I level | |
352 | is outside the range 1 to 8). | |
fea681da | 353 | .TP |
27807c32 MK |
354 | .B ENOSYS |
355 | This | |
356 | .BR syslog () | |
357 | system call is not available, because the kernel was compiled with the | |
358 | .BR CONFIG_PRINTK | |
359 | kernel-configuration option disabled. | |
360 | .TP | |
fea681da | 361 | .B EPERM |
e530d422 MK |
362 | An attempt was made to change |
363 | .I console_loglevel | |
364 | or clear the kernel | |
bb1abbbd | 365 | message ring buffer by a process without sufficient privilege |
0527015d MK |
366 | (more precisely: without the |
367 | .B CAP_SYS_ADMIN | |
dcfe09af MK |
368 | or |
369 | .BR CAP_SYSLOG | |
0527015d | 370 | capability). |
fea681da MK |
371 | .TP |
372 | .B ERESTARTSYS | |
e9496f74 | 373 | System call was interrupted by a signal; nothing was read. |
fea681da | 374 | (This can be seen only during a trace.) |
47297adb | 375 | .SH CONFORMING TO |
8382f16d | 376 | This system call is Linux-specific and should not be used in programs |
fea681da MK |
377 | intended to be portable. |
378 | .SH NOTES | |
e530d422 | 379 | From the very start, people noted that it is unfortunate that |
f484ad49 | 380 | a system call and a library routine of the same name are entirely |
fea681da | 381 | different animals. |
a1402e4c MK |
382 | .\" In libc4 and libc5 the number of this call was defined by |
383 | .\" .BR SYS_klog . | |
384 | .\" In glibc 2.0 the syscall is baptized | |
385 | .\" .BR klogctl (). | |
47297adb | 386 | .SH SEE ALSO |
c0665cd7 | 387 | .BR dmesg (1), |
dcfe09af MK |
388 | .BR syslog (3), |
389 | .BR capabilities (7) |