FMTMSG(3)

ИМЯ
fmtmsg - выводит отформатированные сообщения об ошибках

ОБЗОР
#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.

ЗАМЕЧАНИЯ
В справочных страницах 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).

СМОТРИТЕ ТАКЖЕ
addseverity(3), perror(3)