Debian Codegraph @

upstream/debian-unstable/man2/syslog.2

raw
1 '\" t
2 .\" Copyright 1995, Andries E. Brouwer <[email protected]>
3 .\" Copyright 2012-2014, Michael Kerrisk <[email protected]>
4 .\" Copyright, the authors of the Linux man-pages project
5 .\"
6 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
7 .\"
8 .TH syslog 2 2026-02-08 "Linux man-pages 6.18"
9 .SH NAME
10 syslog, klogctl \- read and/or clear kernel message ring buffer;
11 set console_loglevel
12 .SH LIBRARY
13 Standard C library
14 .RI ( libc ,\~ \-lc )
15 .SH SYNOPSIS
16 .nf
17 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
18 .B #include <unistd.h>
19 .P
20 .BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " size );
21 .P
22 /* The glibc interface */
23 .B #include <sys/klog.h>
24 .P
25 .BI "int klogctl(int " type ", char *" bufp ", int " size );
26 .fi
27 .SH DESCRIPTION
28 .IR Note :
29 Probably, you are looking for the C library function
30 .BR syslog (),
31 which talks to
32 .BR syslogd (8);
33 see
34 .BR syslog (3)
35 for details.
36 .P
37 This page describes the kernel
38 .BR syslog ()
39 system call, which is used to control the kernel
40 .IR printk ()
41 buffer;
42 the glibc wrapper function for the system call is called
43 .BR klogctl ().
44 .SS The kernel log buffer
45 The kernel has a cyclic buffer of size
46 .B LOG_BUF_LEN
47 in which messages given as arguments to the kernel function
48 .BR printk ()
49 are stored (regardless of their log level).
50 In early kernels,
51 .B LOG_BUF_LEN
52 had the value 4096;
53 from Linux 1.3.54, it was 8192;
54 from Linux 2.1.113, it was 16384;
55 since Linux 2.4.23/2.6, the value is a kernel configuration option
56 .RB ( CONFIG_LOG_BUF_SHIFT ,
57 default value dependent on the architecture).
58 .\" Under "General setup" ==> "Kernel log buffer size"
59 .\" For Linux 2.6, precisely the option seems to have appeared in Linux 2.5.55.
60 Since Linux 2.6.6, the size can be queried with command type 10 (see below).
61 .SS Commands
62 The
63 .I type
64 argument determines the action taken by this function.
65 The list below specifies the values for
66 .IR type .
67 The symbolic names are defined in the kernel source,
68 but are not exported to user space;
69 you will either need to use the numbers, or define the names yourself.
70 .TP
71 .BR SYSLOG_ACTION_CLOSE " (0)"
72 Close the log.
73 Currently a NOP.
74 .TP
75 .BR SYSLOG_ACTION_OPEN " (1)"
76 Open the log.
77 Currently a NOP.
78 .TP
79 .BR SYSLOG_ACTION_READ " (2)"
80 Read from the log.
81 The call
82 waits until the kernel log buffer is nonempty, and then reads
83 at most
84 .I len
85 bytes into the buffer pointed to by
86 .IR bufp .
87 The call returns the number of bytes read.
88 Bytes read from the log disappear from the log buffer:
89 the information can be read only once.
90 This is the function executed by the kernel when a user program reads
91 .IR /proc/kmsg .
92 .TP
93 .BR SYSLOG_ACTION_READ_ALL " (3)"
94 Read all messages remaining in the ring buffer,
95 placing them in the buffer pointed to by
96 .IR bufp .
97 The call reads the last
98 .I len
99 bytes from the log buffer (nondestructively),
100 but will not read more than was written into the buffer since the
101 last "clear ring buffer" command (see command 5 below)).
102 The call returns the number of bytes read.
103 .TP
104 .BR SYSLOG_ACTION_READ_CLEAR " (4)"
105 Read and clear all messages remaining in the ring buffer.
106 The call does precisely the same as for a
107 .I type
108 of 3, but also executes the "clear ring buffer" command.
109 .TP
110 .BR SYSLOG_ACTION_CLEAR " (5)"
111 The call executes just the "clear ring buffer" command.
112 The
113 .I bufp
114 and
115 .I size
116 arguments are ignored.
117 .IP
118 This command does not really clear the ring buffer.
119 Rather, it sets a kernel bookkeeping variable that
120 determines the results returned by commands 3
121 .RB ( SYSLOG_ACTION_READ_ALL )
122 and 4
123 .RB ( SYSLOG_ACTION_READ_CLEAR ).
124 This command has no effect on commands 2
125 .RB ( SYSLOG_ACTION_READ )
126 and 9
127 .RB ( SYSLOG_ACTION_SIZE_UNREAD ).
128 .TP
129 .BR SYSLOG_ACTION_CONSOLE_OFF " (6)"
130 The command saves the current value of
131 .I console_loglevel
132 and then sets
133 .I console_loglevel
134 to
135 .IR minimum_console_loglevel ,
136 so that no messages are printed to the console.
137 Before Linux 2.6.32,
138 .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245
139 the command simply sets
140 .I console_loglevel
141 to
142 .IR minimum_console_loglevel .
143 See the discussion of
144 .IR /proc/sys/kernel/printk ,
145 below.
146 .IP
147 The
148 .I bufp
149 and
150 .I size
151 arguments are ignored.
152 .TP
153 .BR SYSLOG_ACTION_CONSOLE_ON " (7)"
154 If a previous
155 .B SYSLOG_ACTION_CONSOLE_OFF
156 command has been performed,
157 this command restores
158 .I console_loglevel
159 to the value that was saved by that command.
160 Before Linux 2.6.32,
161 .\" commit 1aaad49e856ce41adc07d8ae0c8ef35fc4483245
162 this command simply sets
163 .I console_loglevel
164 to
165 .IR default_console_loglevel .
166 See the discussion of
167 .IR /proc/sys/kernel/printk ,
168 below.
169 .IP
170 The
171 .I bufp
172 and
173 .I size
174 arguments are ignored.
175 .TP
176 .BR SYSLOG_ACTION_CONSOLE_LEVEL " (8)"
177 The call sets
178 .I console_loglevel
179 to the value given in
180 .IR size ,
181 which must be an integer between 1 and 8 (inclusive).
182 The kernel silently enforces a minimum value of
183 .I minimum_console_loglevel
184 for
185 .IR size .
186 See the
187 .I log level
188 section for details.
189 The
190 .I bufp
191 argument is ignored.
192 .TP
193 .BR SYSLOG_ACTION_SIZE_UNREAD " (9) (since Linux 2.4.10)"
194 The call
195 returns the number of bytes currently available to be read
196 from the kernel log buffer via command 2
197 .RB ( SYSLOG_ACTION_READ ).
198 The
199 .I bufp
200 and
201 .I size
202 arguments are ignored.
203 .TP
204 .BR SYSLOG_ACTION_SIZE_BUFFER " (10) (since Linux 2.6.6)"
205 This command returns the total size of the kernel log buffer.
206 The
207 .I bufp
208 and
209 .I size
210 arguments are ignored.
211 .P
212 All commands except 3 and 10 require privilege.
213 In Linux kernels before Linux 2.6.37,
214 command types 3 and 10 are allowed to unprivileged processes;
215 since Linux 2.6.37,
216 these commands are allowed to unprivileged processes only if
217 .I /proc/sys/kernel/dmesg_restrict
218 has the value 0.
219 Before Linux 2.6.37, "privileged" means that the caller has the
220 .B CAP_SYS_ADMIN
221 capability.
222 Since Linux 2.6.37,
223 "privileged" means that the caller has either the
224 .B CAP_SYS_ADMIN
225 capability (now deprecated for this purpose) or the (new)
226 .B CAP_SYSLOG
227 capability.
228 .\"
229 .\"
230 .SS /proc/sys/kernel/printk
231 .I /proc/sys/kernel/printk
232 is a writable file containing four integer values that influence kernel
233 .I printk()
234 behavior when printing or logging error messages.
235 The four values are:
236 .TP
237 .I console_loglevel
238 Only messages with a log level lower than this value will
239 be printed to the console.
240 The default value for this field is
241 .B DEFAULT_CONSOLE_LOGLEVEL
242 (7), but it is set to
243 4 if the kernel command line contains the word "quiet",\" since Linux 2.4
244 10 if the kernel command line contains the word "debug",
245 and to 15 in case
246 of a kernel fault (the 10 and 15 are just silly, and equivalent to 8).
247 The value of
248 .I console_loglevel
249 can be set (to a value in the range 1\[en]8) by a
250 .BR syslog ()
251 call with a
252 .I type
253 of 8.
254 .TP
255 .I default_message_loglevel
256 This value will be used as the log level for
257 .I printk()
258 messages that do not have an explicit level.
259 Up to and including Linux 2.6.38,
260 the hard-coded default value for this field was 4
261 .RB ( KERN_WARNING );
262 since Linux 2.6.39,
263 .\" commit 5af5bcb8d37f99ba415a1adc6da71051b84f93a5
264 the default value is defined by the kernel configuration option
265 .BR CONFIG_DEFAULT_MESSAGE_LOGLEVEL ,
266 which defaults to 4.
267 .TP
268 .I minimum_console_loglevel
269 The value in this field is the minimum value to which
270 .I console_loglevel
271 can be set.
272 .TP
273 .I default_console_loglevel
274 This is the default value for
275 .IR console_loglevel .
276 .\"
277 .\"
278 .SS The log level
279 Every
280 .IR printk ()
281 message has its own log level.
282 If the log level is not explicitly specified as part of the message,
283 it defaults to
284 .IR default_message_loglevel .
285 The conventional meaning of the log level is as follows:
286 .TS
287 lB lB lB
288 lB c l.
289 Kernel constant Level value Meaning
290 KERN_EMERG 0 System is unusable
291 KERN_ALERT 1 T{
292 Action must be taken immediately
293 T}
294 KERN_CRIT 2 Critical conditions
295 KERN_ERR 3 Error conditions
296 KERN_WARNING 4 Warning conditions
297 KERN_NOTICE 5 T{
298 Normal but significant condition
299 T}
300 KERN_INFO 6 Informational
301 KERN_DEBUG 7 Debug-level messages
302 .TE
303 .P
304 The kernel
305 .I printk()
306 routine will print a message on the
307 console only if it has a log level less than the value of
308 .IR console_loglevel .
309 .SH RETURN VALUE
310 For
311 .I type
312 equal to 2, 3, or 4, a successful call to
313 .BR syslog ()
314 returns the number
315 of bytes read.
316 For
317 .I type
318 9,
319 .BR syslog ()
320 returns the number of bytes currently
321 available to be read on the kernel log buffer.
322 For
323 .I type
324 10,
325 .BR syslog ()
326 returns the total size of the kernel log buffer.
327 For other values of
328 .IR type ,
329 0 is returned on success.
330 .P
331 In case of error, \-1 is returned,
332 and
333 .I errno
334 is set to indicate the error.
335 .SH ERRORS
336 .TP
337 .B EINVAL
338 Bad arguments (e.g.,
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 size
348 is less than zero;
349 or for
350 .I type
351 8, the
352 .I level
353 is outside the range 1 to 8).
354 .TP
355 .B ENOSYS
356 This
357 .BR syslog ()
358 system call is not available, because the kernel was compiled with the
359 .B CONFIG_PRINTK
360 kernel-configuration option disabled.
361 .TP
362 .B EPERM
363 An attempt was made to change
364 .I console_loglevel
365 or clear the kernel
366 message ring buffer by a process without sufficient privilege
367 (more precisely: without the
368 .B CAP_SYS_ADMIN
369 or
370 .B CAP_SYSLOG
371 capability).
372 .TP
373 .B ERESTARTSYS
374 System call was interrupted by a signal;
375 nothing was read.
376 (This can be seen only during a trace.)
377 .SH STANDARDS
378 Linux.
379 .SH HISTORY
380 From the very start, people noted that it is unfortunate that
381 a system call and a library routine of the same name are entirely
382 different animals.
383 .\" In libc4 and libc5 the number of this call was defined by
384 .\" .BR SYS_klog .
385 .\" In glibc 2.0 the syscall is baptized
386 .\" .BR klogctl ().
387 .SH SEE ALSO
388 .BR dmesg (1),
389 .BR syslog (3),
390 .BR capabilities (7)