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 version is
22 called klogctl().
23 The type argument determines the action taken by this function.
25 Quoting from kernel/printk.c:
27 /*
28 * Commands to sys_syslog:
29 *
30 * 0 -- Close the log. Currently a NOP.
31 * 1 -- Open the log. Currently a NOP.
32 * 2 -- Read from the log.
33 * 3 -- Read all messages remaining in the ring buffer.
34 * 4 -- Read and clear all messages remaining in the ring buffer
35 * 5 -- Clear ring buffer.
36 * 6 -- Disable printk to console
37 * 7 -- Enable printk to console
38 * 8 -- Set level of messages printed to console
39 * 9 -- Return number of unread characters in the log buffer
40 * 10 -- Return size of the log buffer
41 */
42 Only command types 3 and 10 are allowed to unprivileged processes.
44 Type 9 was added in 2.4.10; type 10 in 2.6.6.
45 The kernel log buffer
47 The kernel has a cyclic buffer of length LOG_BUF_LEN in which messages
48 given as arguments to the kernel function printk() are stored (regard‐
49 less of their loglevel). In early kernels, LOG_BUF_LEN had the value
50 4096; from kernel 1.3.54, it was 8192; from kernel 2.1.113 it was
51 16384; since 2.4.23/2.6 the value is a kernel configuration option. In
52 recent kernels the size can be queried with command type 10.
53 The call syslog(2,buf,len) waits until this kernel log buffer is
55 nonempty, and then reads at most len bytes into the buffer buf. It
56 returns the number of bytes read. Bytes read from the log disappear
57 from the log buffer: the information can only be read once. This is
58 the function executed by the kernel when a user program reads
59 /proc/kmsg.
60 The call syslog(3,buf,len) will read the last len bytes from the log
62 buffer (nondestructively), but will not read more than was written into
63 the buffer since the last "clear ring buffer" command (which does not
64 clear the buffer at all). It returns the number of bytes read.
65 The call syslog(4,buf,len) does precisely the same, but also executes
67 the "clear ring buffer" command.
68 The call syslog(5,dummy,dummy) executes just the "clear ring buffer"
70 command. (In each call where buf or len is shown as "dummy", the value
71 of the argument is ignored by the call.)
72 The call syslog(6,dummy,dummy) sets the console log level to minimum,
74 so that no messages are printed to the console.
75 The call syslog(7,dummy,dummy) sets the console log level to default,
77 so that messages are printed to the console.
78 The call syslog(8,dummy,level) sets the console log level to level,
80 which must be an integer between 1 and 8 (inclusive). See the loglevel
81 section for details.
82 The call syslog(9,dummy,dummy) returns the number of bytes currently
84 available to be read on the kernel log buffer.
85 The call syslog(10,dummy,dummy) returns the total size of the kernel
87 log buffer.
88 The loglevel
90 The kernel routine printk() will only print a message on the console,
91 if it has a loglevel less than the value of the variable con‐
92 sole_loglevel. This variable initially has the value DEFAULT_CON‐
93 SOLE_LOGLEVEL (7), but is set to 10 if the kernel command line contains
94 the word "debug", and to 15 in case of a kernel fault (the 10 and 15
95 are just silly, and equivalent to 8). This variable is set (to a value
96 in the range 1-8) by the call syslog(8,dummy,value). The calls sys‐
97 log(type,dummy,dummy) with type equal to 6 or 7, set it to 1 (kernel
98 panics only) or 7 (all except debugging messages), respectively.
99 Every text line in a message has its own loglevel. This level is
101 DEFAULT_MESSAGE_LOGLEVEL - 1 (6) unless the line starts with <d> where
102 d is a digit in the range 1-7, in which case the level is d. The con‐
103 ventional meaning of the loglevel is defined in <linux/kernel.h> as
104 follows:
105 #define KERN_EMERG "<0>" /* system is unusable */
107 #define KERN_ALERT "<1>" /* action must be taken immediately */
108 #define KERN_CRIT "<2>" /* critical conditions */
109 #define KERN_ERR "<3>" /* error conditions */
110 #define KERN_WARNING "<4>" /* warning conditions */
111 #define KERN_NOTICE "<5>" /* normal but significant condition */
112 #define KERN_INFO "<6>" /* informational */
113 #define KERN_DEBUG "<7>" /* debug-level messages */
114
116 For type equal to 2, 3, or 4, a successful call to syslog() returns the
117 number of bytes read. For type 9, syslog() returns the number of bytes
118 currently available to be read on the kernel log buffer. For type 10,
119 syslog() returns the total size of the kernel log buffer. For other
120 values of type, 0 is returned on success.
121 In case of error, -1 is returned, and errno is set to indicate the
123 error.
124
126 EINVAL Bad arguments (e.g., bad type; or for type 2, 3, or 4, buf is
127 NULL, or len is less than zero; or for type 8, the level is out‐
128 side the range 1 to 8).
129 EPERM An attempt was made to change console_loglevel or clear the ker‐
131 nel message ring buffer by a process without sufficient privi‐
132 lege (more precisely: without the CAP_SYS_ADMIN capability).
133 ERESTARTSYS
135 System call was interrupted by a signal; nothing was read.
136 (This can be seen only during a trace.)
137 ENOSYS This syslog() system call is not available, because the kernel
139 was compiled with the CONFIG_PRINTK kernel-configuration option
140 disabled.
141
143 This system call is Linux-specific and should not be used in programs
144 intended to be portable.
145
147 From the very start people noted that it is unfortunate that a system
148 call and a library routine of the same name are entirely different ani‐
149 mals. In libc4 and libc5 the number of this call was defined by
150 SYS_klog. In glibc 2.0 the syscall is baptized klogctl().
151
153 syslog(3)
154
156 This page is part of release 3.25 of the Linux man-pages project. A
157 description of the project, and information about reporting bugs, can
158 be found at http://www.kernel.org/doc/man-pages/.
159Linux 2008-06-20 SYSLOG(2)