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 и 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: ERROR: unknown mount option
    TO FIX: Смотрите mount(8).  util-linux:mount:017

а после

    MSGVERB=text:action; export MSGVERB

вывод станет:

    неизвестный параметр mount
        TO FIX: Смотрите mount(8).

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