Debian Codegraph @

upstream/debian-trixie/man2/syslog.2

raw
1 '\" t
2 .\" Copyright (C) 1995 Andries Brouwer ([email protected])
3 .\" and Copyright (C) 2012, 2014 Michael Kerrisk <[email protected]>
4 .\"
5 .\" SPDX-License-Identifier: Linux-man-pages-copyleft
6 .\"
7 .\" Written 11 June 1995 by Andries Brouwer <[email protected]>
8 .\" 2008-02-15, Jeremy Kerr <[email protected]>
9 .\" Add info on command type 10; add details on types 6, 7, 8, & 9.
10 .\" 2008-02-15, Michael Kerrisk <[email protected]>
11 .\" Update LOG_BUF_LEN details; update RETURN VALUE section.
12 .\"
13 .TH syslog 2 2024-05-02 "Linux man-pages 6.9.1"
14 .SH NAME
15 syslog, klogctl \- read and/or clear kernel message ring buffer;
16 set console_loglevel
17 .SH LIBRARY
18 Standard C library
19 .RI ( libc ", " \-lc )
20 .SH SYNOPSIS
21 .nf
22 .BR "#include <sys/klog.h>" " /* Definition of " SYSLOG_* " constants */"
23 .BR "#include <sys/syscall.h>" " /* Definition of " SYS_* " constants */"
24 .B #include <unistd.h>
25 .P
26 .BI "int syscall(SYS_syslog, int " type ", char *" bufp ", int " len );
27 .P
28 /* The glibc interface */
29 .B #include <sys/klog.h>
30 .P
31 .BI "int klogctl(int " type ", char *" bufp ", int " len );
32 .fi
33 .SH DESCRIPTION
34 .IR Note :
35 Probably, you are looking for the C library function
36 .BR syslog (),
37 which talks to
38 .BR syslogd (8);
39 see
40 .BR syslog (3)
41 for details.
42 .P
43 This page describes the kernel
44 .BR syslog ()
45 system call, which is used to control the kernel
46 .IR printk ()
47 buffer; the glibc wrapper function for the system call is called
48 .BR klogctl ().
49 .SS The kernel log buffer
50 The kernel has a cyclic buffer of length
51 .B LOG_BUF_LEN
52 in which messages given as arguments to the kernel function
53 .BR printk ()
54 are stored (regardless of their log level).
55 In early kernels,
56 .B LOG_BUF_LEN
57 had the value 4096;
58 from Linux 1.3.54, it was 8192;
59 from Linux 2.1.113, it was 16384;
60 since Linux 2.4.23/2.6, the value is a kernel configuration option
61 .RB ( CONFIG_LOG_BUF_SHIFT ,
62 default value dependent on the architecture).
63 .\" Under "General setup" ==> "Kernel log buffer size"
64 .\" For Linux 2.6, precisely the option seems to have appeared in Linux 2.5.55.
65 Since Linux 2.6.6, the size can be queried with command type 10 (see below).
66 .SS Commands
67 The \fItype\fP argument determines the action taken by this function.
68 The list below specifies the values for
69 .IR type .
70 The symbolic names are defined in the kernel source,
71 but are not exported to user space;
72 you will either need to use the numbers, or define the names yourself.
73 .TP
74 .BR SYSLOG_ACTION_CLOSE " (0)"
75 Close the log.
76 Currently a NOP.
77 .TP
78 .BR SYSLOG_ACTION_OPEN " (1)"
79 Open the log.
80 Currently a NOP.
81 .TP
82 .BR SYSLOG_ACTION_READ " (2)"
83 Read from the log.
84 The call
85 waits until the kernel log buffer is nonempty, and then reads
86 at most \fIlen\fP bytes into the buffer pointed to by
87 .IR bufp .
88 The call returns the number of bytes read.
89 Bytes read from the log disappear from the log buffer:
90 the information can be read only once.
91 This is the function executed by the kernel when a user program reads
92 .IR /proc/kmsg .
93 .TP
94 .BR SYSLOG_ACTION_READ_ALL " (3)"
95 Read all messages remaining in the ring buffer,
96 placing them in the buffer pointed to by
97 .IR bufp .
98 The call reads the last \fIlen\fP
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 len
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 len
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 len
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 len ,
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 len .
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 len
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 len
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 \fItype\fP equal to 2, 3, or 4, a successful call to
311 .BR syslog ()
312 returns the number
313 of bytes read.
314 For \fItype\fP 9,
315 .BR syslog ()
316 returns the number of bytes currently
317 available to be read on the kernel log buffer.
318 For \fItype\fP 10,
319 .BR syslog ()
320 returns the total size of the kernel log buffer.
321 For other values of \fItype\fP, 0 is returned on success.
322 .P
323 In case of error, \-1 is returned,
324 and \fIerrno\fP is set to indicate the error.
325 .SH ERRORS
326 .TP
327 .B EINVAL
328 Bad arguments (e.g.,
329 bad
330 .IR type ;
331 or for
332 .I type
333 2, 3, or 4,
334 .I buf
335 is NULL,
336 or
337 .I len
338 is less than zero; or for
339 .I type
340 8, the
341 .I level
342 is outside the range 1 to 8).
343 .TP
344 .B ENOSYS
345 This
346 .BR syslog ()
347 system call is not available, because the kernel was compiled with the
348 .B CONFIG_PRINTK
349 kernel-configuration option disabled.
350 .TP
351 .B EPERM
352 An attempt was made to change
353 .I console_loglevel
354 or clear the kernel
355 message ring buffer by a process without sufficient privilege
356 (more precisely: without the
357 .B CAP_SYS_ADMIN
358 or
359 .B CAP_SYSLOG
360 capability).
361 .TP
362 .B ERESTARTSYS
363 System call was interrupted by a signal; nothing was read.
364 (This can be seen only during a trace.)
365 .SH STANDARDS
366 Linux.
367 .SH HISTORY
368 From the very start, people noted that it is unfortunate that
369 a system call and a library routine of the same name are entirely
370 different animals.
371 .\" In libc4 and libc5 the number of this call was defined by
372 .\" .BR SYS_klog .
373 .\" In glibc 2.0 the syscall is baptized
374 .\" .BR klogctl ().
375 .SH SEE ALSO
376 .BR dmesg (1),
377 .BR syslog (3),
378 .BR capabilities (7)