fmtmsg - выводит отформатированные сообщения об ошибках
fmtmsg(3)
выводит отформатированные сообщения об ошибках
ОБЗОР
#include <fmtmsg.h>
int fmtmsg(long classification, const char *label,
int severity, const char *text,
const char *action, const char *tag);
ОПИСАНИЕ
Эта функция выводит сообщение, описываемое аргументами, на устройство(а),
заданное в аргументе
classification. Для сообщений, записываемых в
stderr, формат зависит от переменной окружения
MSGVERB.
В аргументе label задаётся источник сообщения. Строка должна состоять из
двух частей, разделённых двоеточиями; первая часть должна быть не более 10
символов, а вторая часть — не более 14.
В аргументе text описывается условие ошибки.
В аргументе action описываются возможные шаги по исправлению ошибки. Если
они выводятся, то начинаются с «TO FIX: ».
В аргументе tag указывается ссылка на онлайн-документацию, в которой
можно найти дополнительную информацию. Он должен содержать значение label
и уникальный идентификационный номер.
Фиктивные аргументы
Каждый аргумент может иметь фиктивное значение. Для фиктивного значения
классификации (classification)
MM_NULLMC (0L) ничего не выводится, то
есть ничего не печатается. Фиктивное значение важности (severity)
NO_SEV
(0) указывается, если важность не определена. Значения
MM_NULLLBL,
MM_NULLTXT,
MM_NULLACT,
MM_NULLTAG являются синонимами
((char *) 0) — пустой строки, а
MM_NULLSEV — синоним
NO_SEV.
Аргумент классификации
Аргумент
classification — это сочетание значений, описывающих 4 типа
информации.
Первое значение определяет канал вывода.
MM_PRINT
Вывод в stderr.
MM_CONSOLE
Вывод в системную консоль.
MM_PRINT | MM_CONSOLE
Вывод в оба места.
Вторым значением описывается источник ошибки.
MM_HARD
Произошла аппаратная ошибка.
MM_FIRM
Произошла ошибка в микропрограмме.
MM_SOFT
Произошла ошибка в программном обеспечении.
В третьем значении кодируется выявитель проблемы.
MM_APPL
Обнаружено приложением.
MM_UTIL
Обнаружено утилитой.
MM_OPSYS
Обнаружено операционной системой.
В четвёртом значении показывается важность инцидента:
MM_RECOVER
Это исправимая ошибка.
MM_NRECOV
Это неисправимая ошибка.
Аргумент важности
В аргументе
severity можно указать одно из следующих значений:
MM_NOSEV
Важность не печатается.
MM_HALT
Это значение печатается как ОСТАНОВ.
MM_ERROR
Это значение печатается как ОШИБКА.
MM_WARNING
Это значение печатается как ПРЕДУПРЕЖДЕНИЕ.
MM_INFO
Это значение печатается как ИНФОРМАЦИОННОЕ.
Числовые значения от 0 до 4. Используя функцию addseverity(3) или
переменную окружения SEV_LEVEL вы можете добавить дополнительные уровни и
строки для печати.
ВОЗВРАЩАЕМОЕ ЗНАЧЕНИЕ
Функция может возвращать 4 значения:
MM_OK
Всё хорошо.
MM_NOTOK
Всё плохо.
MM_NOMSG
Ошибка записи в stderr.
MM_NOCON
Ошибка записи в консоль.
ОКРУЖЕНИЕ
Переменная окружения
MSGVERB (message verbosity — детальность сообщения)
может использоваться для отключения некоторых частей вывода в
stderr (она
не влияет на вывод на консоль). Если эта переменная определена, не равна
NULL и содержит список допустимых ключевых слов через двоеточие, то
печатаются только части сообщения, которые соответствуют этим ключевым
словам. Допустимые ключевые слова: «label», «severity», «text», «action» и
«tag».
Переменная окружения SEV_LEVEL может использоваться для ввода новых
уровней важности. По умолчанию, доступно только пять уровней важности,
описанных выше. Для любого другого числового значения fmtmsg() ничего не
печатает. Если пользователь задал SEV_LEVEL в формате
SEV_LEVEL=[описание[:описание[:...]]]
в окружении процесса перед первым вызовом fmtmsg() и каждое описание
имеет вид
ключевое-слово-важности,уровень,печатаемая-строка
то fmtmsg() также будет обрабатывать заданные значения уровней (в
дополнении к стандартным уровням 0-4), и использовать указанную строку
печати, когда встречается такой уровень.
Часть «ключевое-слово-важности» не используется fmtmsg(), но
указывается. Часть «уровень» — это строка, представляющая число. Числовое
значение должно быть числом более 4. Это значение должно использоваться в
аргументе важности fmtmsg() для выбора этого класса. Невозможно заменить
любой из предопределённых классов. «Печатаемая-строка» — строка, которая
печатается в случае, когда сообщение этого класса обрабатывается
fmtmsg().
ВЕРСИИ
Функция
fmtmsg() появилась в glibc начиная с версии 2.1.
АТРИБУТЫ
Описание терминов данного раздела смотрите в
attributes(7).
Интерфейс Атрибут Значение
fmtmsg()
безвредность в потоках:
glibc >= 2.16: MT-Safe
glibc < 2.16: MT-Unsafe
До glibc 2.16 функция fmtmsg() использовала статическую незащищённую
переменную, поэтому функцию нельзя использовать в нескольких нитях
одновременно.
Начиная с glibc 2.16 функция fmtmsg() использует блокировку для защиты
статической переменной, поэтому функцию можно использовать в нескольких
нитях одновременно.
СООТВЕТСТВИЕ СТАНДАРТАМ
Функции
fmtmsg() и
addseverity(3), и переменные окружения
MSGVERB и
SEV_LEVEL впервые появились в System V.
Функция fmtmsg() и переменная окружения MSGVERB описана в POSIX.1-2001
и POSIX.1-2008.
ЗАМЕЧАНИЯ
В справочных страницах System V и UnixWare указано, что эти функции были
заменены на «pfmt() и addsev()» или «pfmt(), vpfmt(), lfmt() и vlfmt()», и
будут впоследствии удалены.
ПРИМЕР
#include <stdio.h>
#include <stdlib.h>
#include <fmtmsg.h>
int
main(void)
{
long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
int err;
err = fmtmsg(class, "util-linux:mount", MM_ERROR,
"неизвестный параметр mount", "Смотрите mount(8).",
"util-linux:mount:017");
switch (err) {
case MM_OK:
break;
case MM_NOTOK:
printf("Нечего печатать\n");
break;
case MM_NOMSG:
printf("Нечего печатать в stderr\n");
break;
case MM_NOCON:
printf("Нет вывода на консоль\n");
break;
default:
printf("Неизвестная ошибка fmtmsg()\n");
}
exit(EXIT_SUCCESS);
}
Вывод должен быть таким:
util-linux:mount: ОШИБКА: неизвестный параметр mount
TO FIX: Смотрите mount(8). util-linux:mount:017
а после
MSGVERB=text:action; export MSGVERB
вывод станет:
неизвестный параметр mount
TO FIX: Смотрите mount(8).
