FMTMSG - Linux手册页
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_NULLLBL，MM_NULLTXT，MM_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)。
| Interface | Attribute | Value |
| fmtmsg() | Thread safety | glibc >= 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/。
