Other Alias
syslog書式
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) を見ること。この名前のシステム・コールはカーネルの printk() バッファを制御するものであり、glibc ラッパー関数は klogctl() と呼ばれている。カーネル・ログ・バッファ (kernel log buffer)
カーネルは長さ 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) で値を設定できるようになっている。最近のカーネルでは、コマンド 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)
- printk のコンソールへの出力を無効にする。 コンソールのログレベルを最小に設定し、 コンソールにメッセージが出力されないようにする。 引き数 bufp と len は無視される。
- SYSLOG_ACTION_CONSOLE_ON (7)
- コンソールのログレベルをデフォルトに設定し、 コンソールにメッセージが表示されるようにする。 引き数 bufp と len は無視される。
- SYSLOG_ACTION_CONSOLE_LEVEL (8)
- コンソールのログレベルを len で指定された値に設定する。 len は 1 以上 8 以下の整数でなければならない。 詳細は ログレベル (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 ケーパビリティを使うのは今は非推奨である)。
ログレベル (loglevel)
カーネル・ルーチンの printk() は、ログレベルが console_loglevel 変数より小さいときにのみ、コンソールにメッセージを表示する。 console_loglevel は最初 DEFAULT_CONSOLE_LOGLEVEL (7) に設定されるが、起動時にカーネルの コマンド・ライン・オプションに "debug" という単語が含まれている場合は 10 に設定され、カーネル・フォールトが発生した場合には 15 に設定される (但し、10 や 15 という数字に意味はなく、8 と同等である)。 この変数は type が 8 の syslog() の呼び出しによって設定され、値の範囲は 1-8 である。 type が 6 もしくは 7 の syslog() の呼び出しの場合、 console_loglevel は 1 (カーネル・パニックのみ)、 7 (デバッグ・メッセージ以外の全て) にそれぞれ設定される。メッセージの各行はそれぞれにログレベルを持つ。このログレベルは DEFAULT_MESSAGE_LOGLEVEL - 1 (6) であるが、 <d> (d は 1-7 の範囲の数字) で始まる行の ログレベルは d である。 ログレベルの慣習的な意味は <linux/kernel.h> に以下のように定義されている:
#define KERN_EMERG "<0>" /* システムが使用不能 */ #define KERN_ALERT "<1>" /* 直ちに対処が必要 */ #define KERN_CRIT "<2>" /* 致命的な状態 */ #define KERN_ERR "<3>" /* エラー状態 */ #define KERN_WARNING "<4>" /* 警告状態 */ #define KERN_NOTICE "<5>" /* 通常状態だが大事な情報 */ #define KERN_INFO "<6>" /* 通知 */ #define KERN_DEBUG "<7>" /* デバッグレベルの情報 */
返り値
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 特有であり、移植を意図したプログラムでは 使用してはいけない。注意
かなり初期の頃から、同じ名前を持つシステムコールとライブラリルーチンが 全く異なる別物であるのは不幸なことだと指摘されてきた。この文書について
この man ページは Linux man-pages プロジェクトのリリース 3.65 の一部 である。プロジェクトの説明とバグ報告に関する情報は http://www.kernel.org/doc/man-pages/ に書かれている。