man 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).