FMTMSG - Linux手册页

时间:2019-08-20 18:00:20  来源:igfitidea点击:

Linux程序员手册 第3部分
更新日期: 2020-06-09

名称

fmtmsg-打印格式化的错误消息

语法

#include <fmtmsg.h>

int fmtmsg(long classification, const char *label,
           int severity, const char *text,
           const char *action, const char *tag);

说明

此函数在分类参数中指定的设备上显示一条由其参数描述的消息。对于写入stderr的消息,格式取决于MSGVERB环境变量。

label参数标识消息的来源。该字符串必须由两个冒号分隔的部分组成,其中第一部分不超过10个字符,第二部分不超过14个字符。

文本参数描述了错误的情况。

action参数描述了从错误中恢复的可能步骤。如果已打印,则以" TO FIX:"为前缀。

tag参数是对联机文档的引用,可以在其中找到更多信息。它应该包含标签值和唯一的标识号。

Dummy arguments

每个参数可以具有一个伪值。虚拟分类值MM_NULLMC(0L)没有指定任何输出,因此不会打印任何内容。虚拟严重性值NO_SEV(0)表示未提供任何严重性。值MM_NULLLBLMM_NULLTXTMM_NULLACT,MM_NULLTAG是((char *)0),空字符串的同义词,而MM_NULLSEV是NO_SEV的同义词。

The classification argument

分类参数是描述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
这是不可恢复的错误。

The severity argument

严重性参数可以采用以下值之一:

MM_NOSEV
没有打印严重性。
MM_HALT
此值显示为HALT。
MM_ERROR
此值显示为ERROR。
MM_WARNING
该值显示为警告。
MM_INFO
此值显示为INFO。

数值介于0到4之间。使用addseverity(3)或环境变量SEV_LEVEL,您可以添加更多级别和字符串以进行打印。

返回值

该函数可以返回4个值:

MM_OK
一切顺利。
MM_NOTOK
完全失败。
MM_NOMSG
写入标准错误。
MM_NOCON
写入控制台时出错。

环境

环境变量MSGVERB("消息详细程度")可用于禁止部分输出到stderr。 (这不会影响到控制台的输出。)定义此变量,将其为非NULL并以冒号分隔的有效关键字列表之后,仅打印消息中与这些关键字相对应的部分。有效的关键字是"标签","严重性","文本","操作"和"标签"。

环境变量SEV_LEVEL可用于引入新的严重性级别。默认情况下,仅上述五个严重性级别可用。任何其他数值将使fmtmsg()不打印任何内容。如果用户使用以下格式输入SEV_LEVEL

SEV_LEVEL = [描述[:描述[:...]]]

在第一次调用fmtmsg()之前的过程环境中,其中每个描述的形式均为

严重程度关键字,级别,打印字符串

然后fmtmsg()还将接受该级别的指示值(除了标准级别0-4),并且在出现这种级别时使用指示的打印字符串。

fmtmsg()不会使用严重性关键字部分,但必须存在它。级别部分是数字的字符串表示形式。该数字值必须大于4。必须在fmtmsg()的严重性参数中使用该值才能选择此类。不可能覆盖任何预定义的类。 printstring是fmtmsg()处理此类消息时打印的字符串。

版本

从2.1版开始,glibc中提供了fmtmsg()。

属性

有关本节中使用的术语的说明,请参见attribute(7)。

InterfaceAttributeValue
fmtmsg()Thread safetyglibc >= 2.16: MT-Safe
glibc < 2.16: MT-Unsafe

在glibc 2.16之前,fmtmsg()函数使用不受保护的静态变量,因此它不是线程安全的。

从glibc 2.16开始,fmtmsg()函数使用锁来保护静态变量,因此它是线程安全的。

遵循规范

函数fmtmsg()和addseverity(3)以及环境变量MSGVERB和SEV_LEVEL来自系统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,
                "unknown mount option", "See mount(8).",
                "util-linux:mount:017");
    switch (err) {
    case MM_OK:
        break;
    case MM_NOTOK:
        printf("Nothing printed\n");
        break;
    case MM_NOMSG:
        printf("Nothing printed to stderr\n");
        break;
    case MM_NOCON:
        printf("No console output\n");
        break;
    default:
        printf("Unknown error from fmtmsg()\n");
    }
    exit(EXIT_SUCCESS);
}

输出应为:

util-linux:mount: ERROR: unknown mount option
TO FIX: See mount(8).  util-linux:mount:017

之后

MSGVERB=text:action; export MSGVERB

输出变为:

unknown mount option
TO FIX: See mount(8).

另外参见

addseverity(3),perror(3)

出版信息

这个页面是Linux手册页项目5.08版的一部分。有关项目的说明、有关报告错误的信息以及此页面的最新版本,请访问https://www.kernel.org/doc/man-pages/