]>
Commit | Line | Data |
---|---|---|
fea681da MK |
1 | .\" Copyright (C) 1995 Andries Brouwer (aeb@cwi.nl) |
2 | .\" | |
3 | .\" Permission is granted to make and distribute verbatim copies of this | |
4 | .\" manual provided the copyright notice and this permission notice are | |
5 | .\" preserved on all copies. | |
6 | .\" | |
7 | .\" Permission is granted to copy and distribute modified versions of this | |
8 | .\" manual under the conditions for verbatim copying, provided that the | |
9 | .\" entire resulting derived work is distributed under the terms of a | |
10 | .\" permission notice identical to this one. | |
11 | .\" | |
12 | .\" Since the Linux kernel and libraries are constantly changing, this | |
13 | .\" manual page may be incorrect or out-of-date. The author(s) assume no | |
14 | .\" responsibility for errors or omissions, or for damages resulting from | |
15 | .\" the use of the information contained herein. The author(s) may not | |
16 | .\" have taken the same level of care in the production of this manual, | |
17 | .\" which is licensed free of charge, as they might when working | |
18 | .\" professionally. | |
19 | .\" | |
20 | .\" Formatted or processed versions of this manual, if unaccompanied by | |
21 | .\" the source, must acknowledge the copyright and authors of this work. | |
22 | .\" | |
23 | .\" Written 11 June 1995 by Andries Brouwer <aeb@cwi.nl> | |
24 | .TH SYSLOG 2 2001-11-25 "Linux 1.2.9" "Linux Programmer's Manual" | |
25 | .SH NAME | |
26 | syslog, klogctl \- read and/or clear kernel message ring buffer; set console_loglevel | |
27 | .SH SYNOPSIS | |
28 | .nf | |
29 | /* The glibc interface */ | |
30 | .br | |
31 | .B "#include <sys/klog.h>" | |
32 | .sp | |
33 | .BI "int klogctl(int " type ", char *" bufp ", int " len ); | |
34 | .sp | |
35 | /* The handcrafted system call */ | |
36 | .br | |
37 | .B #include <unistd.h> | |
38 | .br | |
39 | .B #include <linux/unistd.h> | |
527d9933 MK |
40 | .br |
41 | .B #include <errno.h> | |
fea681da | 42 | .sp |
25743dd7 | 43 | .B _syscall3(int, syslog, int, type, char *, bufp, int, len) |
fea681da MK |
44 | .sp |
45 | .BI "int syslog(int " type ", char *" bufp ", int " len ); | |
46 | .fi | |
47 | .SH DESCRIPTION | |
48 | If you need the libc function | |
63aa9df0 | 49 | .BR syslog (), |
fea681da MK |
50 | (that talks to |
51 | .BR syslogd (8)), | |
52 | then look at | |
53 | .BR syslog (3). | |
54 | The system call of this name is about controlling the kernel | |
63aa9df0 | 55 | .IR printk () |
fea681da | 56 | buffer, and the glibc version is called |
63aa9df0 | 57 | .BR klogctl (). |
fea681da MK |
58 | |
59 | The \fItype\fP argument determines the action taken by this function. | |
60 | ||
61 | Quoting from | |
62 | .IR kernel/printk.c : | |
63 | .nf | |
64 | /* | |
65 | * Commands to sys_syslog: | |
66 | * | |
2bc2f479 MK |
67 | * 0 \-\- Close the log. Currently a NOP. |
68 | * 1 \-\- Open the log. Currently a NOP. | |
69 | * 2 \-\- Read from the log. | |
70 | * 3 \-\- Read up to the last 4k of messages in the ring buffer. | |
71 | * 4 \-\- Read and clear last 4k of messages in the ring buffer | |
72 | * 5 \-\- Clear ring buffer. | |
73 | * 6 \-\- Disable printk's to console | |
74 | * 7 \-\- Enable printk's to console | |
75 | * 8 \-\- Set level of messages printed to console | |
76 | * 9 \-\- Return number of unread characters in the log buffer | |
fea681da MK |
77 | */ |
78 | .fi | |
79 | ||
80 | Only function 3 is allowed to non-root processes. | |
81 | (Function 9 was added in 2.4.10.) | |
82 | ||
83 | .B The kernel log buffer | |
84 | .br | |
85 | The kernel has a cyclic buffer of length LOG_BUF_LEN | |
86 | (4096, since 1.3.54: 8192, since 2.1.113: 16384; in recent kernels | |
87 | the size can be set at compile time) in which messages given as argument | |
88 | to the kernel function \fIprintk\fP() are stored | |
89 | (regardless of their loglevel). | |
90 | ||
91 | The call | |
e511ffb6 | 92 | .BR syslog () |
fea681da MK |
93 | .RI (2, buf , len ) |
94 | waits until this kernel log buffer is nonempty, and then reads | |
95 | at most \fIlen\fP bytes into the buffer \fIbuf\fP. It returns | |
96 | the number of bytes read. Bytes read from the log disappear from | |
97 | the log buffer: the information can only be read once. | |
98 | This is the function executed by the kernel when a user program | |
99 | reads | |
100 | .IR /proc/kmsg . | |
101 | ||
102 | The call | |
e511ffb6 | 103 | .BR syslog () |
fea681da MK |
104 | .RI (3, buf , len ) |
105 | will read the last \fIlen\fP bytes from the log buffer (nondestructively), | |
106 | but will not read more than was written into the buffer since the | |
107 | last `clear ring buffer' command (which does not clear the buffer at all). | |
108 | It returns the number of bytes read. | |
109 | ||
110 | The call | |
e511ffb6 | 111 | .BR syslog () |
fea681da MK |
112 | .RI (4, buf , len ) |
113 | does precisely the same, but also executes the `clear ring buffer' command. | |
114 | ||
115 | The call | |
e511ffb6 | 116 | .BR syslog () |
fea681da MK |
117 | .RI (5, dummy , idummy ) |
118 | only executes the `clear ring buffer' command. | |
119 | ||
120 | .B The loglevel | |
121 | .br | |
122 | The kernel routine \fIprintk\fP() will only print a message on the | |
123 | console, if it has a loglevel less than the value of the variable | |
e9496f74 MK |
124 | .IR console_loglevel . |
125 | This variable initially has the value DEFAULT_CONSOLE_LOGLEVEL (7), | |
126 | but is set to 10 if the | |
d301ee6c | 127 | kernel command line contains the word `debug', and to 15 in case |
e9496f74 | 128 | of a kernel fault (the 10 and 15 are just silly, and equivalent to 8). |
fea681da | 129 | This variable is set (to a value in the range 1-8) by the call |
e511ffb6 | 130 | .BR syslog () |
fea681da MK |
131 | .RI (8, dummy , value ). |
132 | The calls | |
e511ffb6 | 133 | .BR syslog () |
fea681da MK |
134 | .RI ( type , dummy , idummy ) |
135 | with \fItype\fP equal to 6 or 7, set it to 1 (kernel panics only) | |
136 | or 7 (all except debugging messages), respectively. | |
137 | ||
138 | Every text line in a message has its own loglevel. This level is | |
e9496f74 | 139 | DEFAULT_MESSAGE_LOGLEVEL \- 1 (6) unless the line starts with <d> |
fea681da MK |
140 | where \fId\fP is a digit in the range 1-7, in which case the level |
141 | is \fId\fP. The conventional meaning of the loglevel is defined in | |
142 | .I <linux/kernel.h> | |
143 | as follows: | |
144 | ||
145 | .nf | |
146 | #define KERN_EMERG "<0>" /* system is unusable */ | |
147 | #define KERN_ALERT "<1>" /* action must be taken immediately */ | |
148 | #define KERN_CRIT "<2>" /* critical conditions */ | |
149 | #define KERN_ERR "<3>" /* error conditions */ | |
150 | #define KERN_WARNING "<4>" /* warning conditions */ | |
151 | #define KERN_NOTICE "<5>" /* normal but significant condition */ | |
152 | #define KERN_INFO "<6>" /* informational */ | |
153 | #define KERN_DEBUG "<7>" /* debug-level messages */ | |
154 | .fi | |
155 | ||
156 | .SH "RETURN VALUE" | |
157 | In case of error, \-1 is returned, and \fIerrno\fP is set. Otherwise, | |
158 | for \fItype\fP equal to 2, 3 or 4, \fBsyslog\fP() returns the number | |
159 | of bytes read, and otherwise 0. | |
160 | .SH ERRORS | |
161 | .TP | |
162 | .B EINVAL | |
163 | Bad parameters. | |
164 | .TP | |
165 | .B EPERM | |
166 | An attempt was made to change console_loglevel or clear the kernel | |
167 | message ring buffer by a process without root permissions. | |
168 | .TP | |
169 | .B ERESTARTSYS | |
e9496f74 | 170 | System call was interrupted by a signal; nothing was read. |
fea681da MK |
171 | (This can be seen only during a trace.) |
172 | .SH "CONFORMING TO" | |
173 | This system call is Linux specific and should not be used in programs | |
174 | intended to be portable. | |
175 | .SH NOTES | |
176 | From the very start people noted that it is unfortunate that | |
177 | kernel call and library routine of the same name are entirely | |
178 | different animals. | |
179 | In libc4 and libc5 the number of this call was defined by | |
180 | .BR SYS_klog . | |
181 | In glibc 2.0 the syscall is baptised | |
e511ffb6 | 182 | .BR klogctl (). |
fea681da MK |
183 | |
184 | .SH "SEE ALSO" | |
185 | .BR syslog (3) |