syslog, klogctl -
カーネルのメッセージリングバッファーを読んだり消去したりする;
console_loglevel の設定を行う
int syslog(int type, char *bufp, int len);
/* glibc ではラッパー関数は提供されていない */
/* glibc インターフェース */
#include <sys/klog.h>
int klogctl(int type, char *bufp, int len);
注意:
おそらく、あなたが探しているのは、
syslogd(8) と通信する C
ライブラリ関数の
syslog()
でしょう。詳細は
syslog(3) を参照のこと。
このページはカーネルの
syslog()
システムコールについて説明している。
syslog()
システムコールはカーネルの
printk()
バッファーを制御するために使用される。
このシステムコールに対する
glibc ラッパー関数は
klogctl()
と呼ばれている。
カーネルは長さ
LOG_BUF_LEN
の巡回式のバッファーを持っており、
それにはカーネル関数の
printk()
の引数として与えられた
メッセージが
(そのログレベルにかかわらず)
格納される。
初期のカーネルでは
LOG_BUF_LEN の値は 4096
であった。 カーネル
1.3.54 からは 8192、 カーネル
2.1.113 からは 16384 になり、
カーネル 2.4.23
以降および 2.6
以降ではカーネル設定オプション
(
CONFIG_LOG_BUF_SHIFT、
デフォルト値はアーキテクチャー依存)
で値を設定できるようになっている。
Linux 2.6.6
以降では、コマンド 10
(下記参照)
でバッファーのサイズを問い合わせできる。
type
引数はこの関数が行う動作を決定する。
以下のリストに示す値を
type に指定できる。
シンボル名はカーネルソースで定義されているが、ユーザー空間には公開されていない。
したがって、数字を使うか、名前を自分で定義する必要がある。
-
SYSLOG_ACTION_CLOSE (0)
- ログをクローズする。現在のところ
NOP である。
-
SYSLOG_ACTION_OPEN (1)
- ログをオープンする。現在のところ
NOP である。
-
SYSLOG_ACTION_READ (2)
- ログを読み出す。
この呼び出しは、
カーネルログバッファーが空でなくなるまで待って、
最大 len バイトまで
bufp
が指すバッファーに読み込み、
読み込んだバイト数を返す。
ログから読まれたバイトはログバッファーから消える。
つまり、情報は一度しか読むことができない。
これはユーザーのプログラムが
/proc/kmsg
を読んだ時にカーネルによって実行される関数でもある。
-
SYSLOG_ACTION_READ_ALL (3)
- リングバッファーに残っているメッセージをすべて読み出し、
bufp
が指すバッファーに格納する。
この呼び出しログバッファーの最後の
len バイトを
(非破壊的に)
読み出すが、
最後の「リングバッファー消去」命令
(下記のコマンド 5
参照)
以降にバッファーに書き込まれた情報しか読み出せない。
返り値は読み込んだバイト数である。
-
SYSLOG_ACTION_READ_CLEAR (4)
- リングバッファーに残っているメッセージをすべて読み出し、クリアする。
この呼び出しは type 3
と全く同じことを行い、追加で「リングバッファー消去」
("clear ring buffer")
コマンドも実行する。
-
SYSLOG_ACTION_CLEAR (5)
- 「リングバッファー消去」
( は無視される。
- このコマンドは実際にリングバッファーをクリアするわけではなく、
コマンド 3 ( SYSLOG_ACTION_READ_ALL)
と 4 ( SYSLOG_ACTION_READ_CLEAR
で返す内容を決定するカーネルの管理変数を設定する。
このコマンドはコマンド
2 ( SYSLOG_ACTION_READ) と 9
(SYSLOG_ACTION_SIZE_UNREAD)
には影響を与えない。
-
SYSLOG_ACTION_CONSOLE_OFF (6)
- このコマンドは
console_loglevel
の現在の値を保存し、それから
console_loglevel を minimum_console_loglevel
に設定する。
これにより、コンソールにメッセージが出力されなくなる。
Linux 2.6.32 より前では、
このコマンドは
console_loglevel を minimum_console_loglevel
に設定するだけであった。
下記の /proc/sys/kernel/printk
の議論を参照。
- 引数 bufp と len
は無視される。
-
SYSLOG_ACTION_CONSOLE_ON (7)
- 直前に SYSLOG_ACTION_CONSOLE_OFF
コマンドがされた場合、
このコマンドは
console_loglevel
を前のコマンドが保存した値に戻す。
Linux 2.6.32 より前では、
このコマンドは単に
console_loglevel を default_console_loglevel
に設定するだけであった。
下記の /proc/sys/kernel/printk
の議論を参照。
- 引数 bufp と len
は無視される。
-
SYSLOG_ACTION_CONSOLE_LEVEL (8)
-
console_loglevel を len
で指定された値に設定する。
len は 1 以上 8
以下の整数でなければならない。
カーネルにより、暗黙のうちに
len に minimum_console_loglevel
で指定される最小値が適用される。
詳細は「ログレベル」の節を参照のこと。
引数 bufp
は無視される。
-
SYSLOG_ACTION_SIZE_UNREAD (9) (Linux 2.4.10
以降)
- コマンド 2
(SYSLOG_ACTION_READ)
でカーネルログバッファーから読み出せるバイト数を返す。
引数 bufp と len
は無視される。
-
SYSLOG_ACTION_SIZE_BUFFER (10) (Linux 2.6.6
以降)
- カーネルログバッファーの全体のサイズを返す。
引数 bufp と len
は無視される。
コマンド種別 3 と 10
以外のコマンドは全て特権が必要である。
バージョン 2.6.37
より前の Linux
カーネルでは、
コマンド種別 3 と 10
は非特権プロセスも呼び出すことができる。
Linux 2.6.37 以降では、
/proc/sys/kernel/dmesg_restrict が値 0
の場合に限り、
非特権プロセスはこれらのコマンドを呼び出すことができる。
Linux 2.6.37
より前では、「特権を持つ
(privileged)」とは呼び出し者が
CAP_SYS_ADMIN
ケーパビリティを持つことを意味する。
Linux 2.6.37
以降では、「特権を持つ」とは呼び出し者が
CAP_SYS_ADMIN
ケーパビリティか
(新しい)
CAP_SYSLOG
ケーパビリティのいずれかを持つことを意味する
(この目的で
CAP_SYS_ADMIN
ケーパビリティを使うのは今は非推奨である)。
/proc/sys/kernel/printk
は書き込み可能なファイルで、
エラーメッセージのログ出力を行う際にカーネルの
printk()
の動作に影響を持つ 4
つの整数値が入っている。
4
つの値は以下のとおりである。
- console_loglevel
- メッセージのログレベルがこの値よりも小さい場合のみ、メッセージだけがコンソールに出力される。
このフィールドのデフォルト値は
DEFAULT_CONSOLE_LOGLEVEL (7) だが、
カーネルのコマンドラインに
"quiet"
という単語が含まれている場合は
4 に設定され、 "debug"
という単語が含まれている場合は
10 に設定され、
カーネルフォールトが発生した場合には
15 に設定される
(但し、10 や 15
という数字に意味はなく、8
と同等である)。
console_loglevel の値は type が 8
の syslog()
の呼び出しによって設定でき、
設定できる値の範囲は
1–8 である。
- default_message_loglevel
- この値は、明示的にログレベルが指定されていない
printk()
メッセージのログレベルとして使用される。
Linux 2.6.38 以前では、
このフィールドのデフォルト値は
4 ( KERN_WARNING)
にハードコードされていた。
Linux 2.6.39 以降では、
デフォルト値はカーネルの設定オプション
CONFIG_DEFAULT_MESSAGE_LOGLEVEL
で定義されており、
デフォルト値は 4
である。
- minimum_console_loglevel
- このフィールドの値は
console_loglevel
に設定できる最小値である。
- default_console_loglevel
-
console_loglevel
のデフォルト値である。
すべての
printk()
メッセージにはそれぞれログレベルがある。
ログレベルがメッセージの一部として明示的に指定されなかった場合は、
ログレベルは
default_message_loglevel
になる。ログレベルの一般的な意味は以下のとおりである。
| カーネル定数 |
レベル値 |
意味 |
| KERN_EMERG |
0 |
システムが使用不可 |
| KERN_ALERT |
1 |
直ちに対応しなければならない |
| KERN_CRIT |
2 |
危険な状況 |
| KERN_ERR |
3 |
エラー状況 |
| KERN_WARNING |
4 |
警告状況 |
| KERN_NOTICE |
5 |
通常だが重要な状況 |
| KERN_INFO |
6 |
参考情報 |
| KERN_DEBUG |
7 |
デバッグレベルのメッセージ |
カーネルの
printk()
ルーチンは、メッセージのログレベルが
console_loglevel
よりも小さい値の場合にのみ、
メッセージをコンソールに出力する。
type が 2, 3, 4
の場合、成功すると
syslog()
は読み出したバイト数を返す。
type が 9 の場合、
カーネルログバッファーにある現在読み出し可能なバイト数を返す。
type が 10 の場合、
カーネルログバッファーの総量を返す。
type
がそれ以外の値の場合、成功すると
0 が返される。
エラーの場合は、-1 が返り、
errno
にエラーを示す値が設定される。
- EINVAL
- 不正な引数
(具体的には、 type
が正しくない、もしくは
type が 2, 3, 4 の場合に buf
が NULL か len が 0
未満である、もしくは
type が 8 の場合に level
が 1 以上 8
以下の範囲に入っていない)。
- ENOSYS
- カーネルの設定オプション
CONFIG_PRINTK
を無効にしてカーネルがコンパイルされているため、
syslog()
システムコールが利用できない。
- EPERM
- 十分な権限を持たないプロセス
(正確にはケーパビリティ
CAP_SYS_ADMIN も CAP_SYSLOG
も持たないプロセス)
が console_loglevel
を変更しようとしたか、
カーネルメッセージリングを消去しようとした。
- ERESTARTSYS
- システムコールがシグナルによって割り込まれ、何も読み出せなかった。
(トレース中にしか発生することはない)
このシステムコールは
Linux
特有であり、移植を意図したプログラムでは
使用してはいけない。
かなり初期の頃から、同じ名前を持つシステムコールとライブラリルーチンが
全く異なる別物であるのは不幸なことだと指摘されてきた。
dmesg(1),
syslog(3),
capabilities(7)
この man ページは Linux
man-pages
プロジェクトのリリース
5.10
の一部である。プロジェクトの説明とバグ報告に関する情報は
https://www.kernel.org/doc/man-pages/
に書かれている。