ОБЗОР

int syslog(int type, char *bufp, int len);
/* не имеет обёртки в glibc */

---

/* интерфейс glibc */
#include <sys/klog.h>

---

int klogctl(int type, char *bufp, int len);

ОПИСАНИЕ

Замечание: Вероятно, вы ищете библиотечную функцию Си syslog(), которая описана в syslogd(8); подробности смотрите в syslog(3).

В этой странице описана системный вызов ядра 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)

Закрыть журнал. Ничего не делает.

SYSLOG_ACTION_OPEN (1)

Открыть журнал. Ничего не делает.

SYSLOG_ACTION_READ (2)

Читать из журнала. Вызов ждёт пока в буфере журнала ядра что-нибудь не появится и затем записывает максимум len байт в буфер, указанный bufp. Вызов возвращает количество прочитанных байт. Байты, прочитанные из журнала, исчезают из буфера журнала: информацию можно прочесть только один раз. Эта функция используется ядром когда пользовательская программа читает файл /proc/kmsg.

SYSLOG_ACTION_READ_ALL (3)

Читать все сообщения, оставшиеся в кольцевом буфере, помещая их в буфер, указанный в bufp. Вызов читает последние len байт из буфера журнала (не разрушая его), но не больше, чем было записано в буфер с момента вызова команды «очистка кольцевого буфера» (смотрите команду 5 далее). Вызов возвращает количество прочитанных байт.

SYSLOG_ACTION_READ_CLEAR (4)

Прочитать и стереть все сообщения, оставшиеся в кольцевом буфере. Вызов выполняет то же самое, что и при type равном 3, но ещё вызывает команду «очистка кольцевого буфера».

SYSLOG_ACTION_CLEAR (5)

Вызов просто исполняет команду «очистка кольцевого буфера». Аргументы bufp и len игнорируются.

Эта команда на самом деле не очищает кольцевой буфер. Вместо этого она изменяет переменную учёта в ядре, которая определяет результат, возвращаемый командами 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, которое должно быть целым числом от 1 до 8 (включительно). Ядро неявно изменяет минимальное значение minimum_console_loglevel на len. Подробности смотрите в разделе Уровень протоколирования. Аргумент 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 требуют привилегий. В ядрах Linux до версии 2.6.37, команды 3 и 10 были доступны непривилегированным процессам; начиная с Linux 2.6.37, эти команды разрешены из непривилегированных процессов только, если значение /proc/sys/kernel/dmesg_restrict равно 0. До Linux 2.6.37 под «привилегиями» понималось, что вызывающий имеет мандат CAP_SYS_ADMIN. Начиная с Linux 2.6.37 «привилегией» считается, что вызывающий имеет либо мандат CAP_SYS_ADMIN (теперь устарел для такого использования), либо (новый) мандат CAP_SYSLOG.

/proc/sys/kernel/printk

Файл /proc/sys/kernel/printk доступен на запись и содержит 4 целочисленных значения, которыми управляется поведение ядерного printk() при печати или протоколировании сообщений об ошибках. Четыре значения:

console_loglevel

На консоль выводятся только сообщения, у которых уровень протоколирования меньше этого значения. По умолчанию значение этой переменной равно DEFAULT_CONSOLE_LOGLEVEL (7), но это значение будет равно 4, если командная строка ядра содержит слово «quiet»; 10 — если командная строка ядра содержит слово «debug», и 15 — в случае ошибки ядра (10 и 15 не имеют большого смысла и аналогичны 8). Значение (из диапазона от 1 до 8) console_loglevel устанавливается вызовом syslog() с type равным 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, syslog() возвращает количество байт, доступных для чтения из кольцевого буфера ядра. При type равном 10, syslog() возвращает полный размер кольцевого буфера ядра. При других значениях type и успешном выполнении возвращается 0.

При ошибке возвращается -1, а переменной errno присваивается номер ошибки.

СООТВЕТСТВИЕ СТАНДАРТАМ

Данный системный вызов существует только в Linux и не должен использоваться переносимых программах.

ЗАМЕЧАНИЯ

С самого начала многим не нравится, что вызов ядра и библиотечная функция с одинаковыми именами делают совершенно разные вещи.