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