|
Packit |
7cfc04 |
.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_START(GPL_NOVERSION_ONELINE)
|
|
Packit |
7cfc04 |
.\" Distributed under GPL
|
|
Packit |
7cfc04 |
.\" %%%LICENSE_END
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" adapted glibc info page
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" This should run as 'Guru Meditation' (amiga joke :)
|
|
Packit |
7cfc04 |
.\" The function is quite complex and deserves an example
|
|
Packit |
7cfc04 |
.\"
|
|
Packit |
7cfc04 |
.\" Polished, aeb, 2003-11-01
|
|
Packit |
7cfc04 |
.TH FMTMSG 3 2017-09-15 "" "Linux Programmer's Manual"
|
|
Packit |
7cfc04 |
.SH NAME
|
|
Packit |
7cfc04 |
fmtmsg \- print formatted error messages
|
|
Packit |
7cfc04 |
.SH SYNOPSIS
|
|
Packit |
7cfc04 |
.nf
|
|
Packit |
7cfc04 |
.B #include <fmtmsg.h>
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.BI "int fmtmsg(long " classification ", const char *" label ,
|
|
Packit |
7cfc04 |
.BI " int " severity ", const char *" text ,
|
|
Packit |
7cfc04 |
.BI " const char *" action ", const char *" tag );
|
|
Packit |
7cfc04 |
.fi
|
|
Packit |
7cfc04 |
.SH DESCRIPTION
|
|
Packit |
7cfc04 |
This function displays a message described by its arguments on the device(s)
|
|
Packit |
7cfc04 |
specified in the
|
|
Packit |
7cfc04 |
.I classification
|
|
Packit |
7cfc04 |
argument.
|
|
Packit |
7cfc04 |
For messages written to
|
|
Packit |
7cfc04 |
.IR stderr ,
|
|
Packit |
7cfc04 |
the format depends on the
|
|
Packit |
7cfc04 |
.B MSGVERB
|
|
Packit |
7cfc04 |
environment variable.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I label
|
|
Packit |
7cfc04 |
argument identifies the source of the message.
|
|
Packit |
7cfc04 |
The string must consist
|
|
Packit |
7cfc04 |
of two colon separated parts where the first part has not more
|
|
Packit |
7cfc04 |
than 10 and the second part not more than 14 characters.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I text
|
|
Packit |
7cfc04 |
argument describes the condition of the error.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I action
|
|
Packit |
7cfc04 |
argument describes possible steps to recover from the error.
|
|
Packit |
7cfc04 |
If it is printed, it is prefixed by "TO FIX: ".
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I tag
|
|
Packit |
7cfc04 |
argument is a reference to the online documentation where more
|
|
Packit |
7cfc04 |
information can be found.
|
|
Packit |
7cfc04 |
It should contain the
|
|
Packit |
7cfc04 |
.I label
|
|
Packit |
7cfc04 |
value and a unique identification number.
|
|
Packit |
7cfc04 |
.SS Dummy arguments
|
|
Packit |
7cfc04 |
Each of the arguments can have a dummy value.
|
|
Packit |
7cfc04 |
The dummy classification value
|
|
Packit |
7cfc04 |
.B MM_NULLMC
|
|
Packit |
7cfc04 |
(0L) does not specify any output, so nothing is printed.
|
|
Packit |
7cfc04 |
The dummy severity value
|
|
Packit |
7cfc04 |
.B NO_SEV
|
|
Packit |
7cfc04 |
(0) says that no severity is supplied.
|
|
Packit |
7cfc04 |
The values
|
|
Packit |
7cfc04 |
.BR MM_NULLLBL ,
|
|
Packit |
7cfc04 |
.BR MM_NULLTXT ,
|
|
Packit |
7cfc04 |
.BR MM_NULLACT ,
|
|
Packit |
7cfc04 |
.B MM_NULLTAG
|
|
Packit |
7cfc04 |
are synonyms for
|
|
Packit |
7cfc04 |
.IR "((char\ *)\ 0)" ,
|
|
Packit |
7cfc04 |
the empty string, and
|
|
Packit |
7cfc04 |
.B MM_NULLSEV
|
|
Packit |
7cfc04 |
is a synonym for
|
|
Packit |
7cfc04 |
.BR NO_SEV .
|
|
Packit |
7cfc04 |
.SS The classification argument
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I classification
|
|
Packit |
7cfc04 |
argument is the sum of values describing 4 types of information.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The first value defines the output channel.
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_PRINT
|
|
Packit |
7cfc04 |
Output to
|
|
Packit |
7cfc04 |
.IR stderr .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_CONSOLE
|
|
Packit |
7cfc04 |
Output to the system console.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B "MM_PRINT | MM_CONSOLE"
|
|
Packit |
7cfc04 |
Output to both.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The second value is the source of the error:
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_HARD
|
|
Packit |
7cfc04 |
A hardware error occurred.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_FIRM
|
|
Packit |
7cfc04 |
A firmware error occurred.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_SOFT
|
|
Packit |
7cfc04 |
A software error occurred.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The third value encodes the detector of the problem:
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_APPL
|
|
Packit |
7cfc04 |
It is detected by an application.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_UTIL
|
|
Packit |
7cfc04 |
It is detected by a utility.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_OPSYS
|
|
Packit |
7cfc04 |
It is detected by the operating system.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The fourth value shows the severity of the incident:
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_RECOVER
|
|
Packit |
7cfc04 |
It is a recoverable error.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_NRECOV
|
|
Packit |
7cfc04 |
It is a nonrecoverable error.
|
|
Packit |
7cfc04 |
.SS The severity argument
|
|
Packit |
7cfc04 |
The
|
|
Packit |
7cfc04 |
.I severity
|
|
Packit |
7cfc04 |
argument can take one of the following values:
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_NOSEV
|
|
Packit |
7cfc04 |
No severity is printed.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_HALT
|
|
Packit |
7cfc04 |
This value is printed as HALT.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_ERROR
|
|
Packit |
7cfc04 |
This value is printed as ERROR.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_WARNING
|
|
Packit |
7cfc04 |
This value is printed as WARNING.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_INFO
|
|
Packit |
7cfc04 |
This value is printed as INFO.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The numeric values are between 0 and 4.
|
|
Packit |
7cfc04 |
Using
|
|
Packit |
7cfc04 |
.BR addseverity (3)
|
|
Packit |
7cfc04 |
or the environment variable
|
|
Packit |
7cfc04 |
.B SEV_LEVEL
|
|
Packit |
7cfc04 |
you can add more levels and strings to print.
|
|
Packit |
7cfc04 |
.SH RETURN VALUE
|
|
Packit |
7cfc04 |
The function can return 4 values:
|
|
Packit |
7cfc04 |
.TP 12n
|
|
Packit |
7cfc04 |
.B MM_OK
|
|
Packit |
7cfc04 |
Everything went smooth.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_NOTOK
|
|
Packit |
7cfc04 |
Complete failure.
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_NOMSG
|
|
Packit |
7cfc04 |
Error writing to
|
|
Packit |
7cfc04 |
.IR stderr .
|
|
Packit |
7cfc04 |
.TP
|
|
Packit |
7cfc04 |
.B MM_NOCON
|
|
Packit |
7cfc04 |
Error writing to the console.
|
|
Packit |
7cfc04 |
.SH ENVIRONMENT
|
|
Packit |
7cfc04 |
The environment variable
|
|
Packit |
7cfc04 |
.B MSGVERB
|
|
Packit |
7cfc04 |
("message verbosity") can be used to suppress parts of
|
|
Packit |
7cfc04 |
the output to
|
|
Packit |
7cfc04 |
.IR stderr .
|
|
Packit |
7cfc04 |
(It does not influence output to the console.)
|
|
Packit |
7cfc04 |
When this variable is defined, is non-NULL, and is a colon-separated
|
|
Packit |
7cfc04 |
list of valid keywords, then only the parts of the message corresponding
|
|
Packit |
7cfc04 |
to these keywords is printed.
|
|
Packit |
7cfc04 |
Valid keywords are "label", "severity", "text", "action" and "tag".
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The environment variable
|
|
Packit |
7cfc04 |
.B SEV_LEVEL
|
|
Packit |
7cfc04 |
can be used to introduce new severity levels.
|
|
Packit |
7cfc04 |
By default, only the five severity levels described
|
|
Packit |
7cfc04 |
above are available.
|
|
Packit |
7cfc04 |
Any other numeric value would make
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
print nothing.
|
|
Packit |
7cfc04 |
If the user puts
|
|
Packit |
7cfc04 |
.B SEV_LEVEL
|
|
Packit |
7cfc04 |
with a format like
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
SEV_LEVEL=[description[:description[:...]]]
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
in the environment of the process before the first call to
|
|
Packit |
7cfc04 |
.BR fmtmsg (),
|
|
Packit |
7cfc04 |
where each description is of the form
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.RS
|
|
Packit |
7cfc04 |
severity-keyword,level,printstring
|
|
Packit |
7cfc04 |
.RE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
then
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
will also accept the indicated values for the level (in addition to
|
|
Packit |
7cfc04 |
the standard levels 0\(en4), and use the indicated printstring when
|
|
Packit |
7cfc04 |
such a level occurs.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The severity-keyword part is not used by
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
but it has to be present.
|
|
Packit |
7cfc04 |
The level part is a string representation of a number.
|
|
Packit |
7cfc04 |
The numeric value must be a number greater than 4.
|
|
Packit |
7cfc04 |
This value must be used in the severity argument of
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
to select this class.
|
|
Packit |
7cfc04 |
It is not possible to overwrite
|
|
Packit |
7cfc04 |
any of the predefined classes.
|
|
Packit |
7cfc04 |
The printstring
|
|
Packit |
7cfc04 |
is the string printed when a message of this class is processed by
|
|
Packit |
7cfc04 |
.BR fmtmsg ().
|
|
Packit |
7cfc04 |
.SH VERSIONS
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
is provided in glibc since version 2.1.
|
|
Packit |
7cfc04 |
.SH ATTRIBUTES
|
|
Packit |
7cfc04 |
For an explanation of the terms used in this section, see
|
|
Packit |
7cfc04 |
.BR attributes (7).
|
|
Packit |
7cfc04 |
.TS
|
|
Packit |
7cfc04 |
allbox;
|
|
Packit |
7cfc04 |
lb lb lbw23
|
|
Packit |
7cfc04 |
l l l.
|
|
Packit |
7cfc04 |
Interface Attribute Value
|
|
Packit |
7cfc04 |
T{
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
T} Thread safety T{
|
|
Packit |
7cfc04 |
glibc >= 2.16: MT-Safe
|
|
Packit |
7cfc04 |
.br
|
|
Packit |
7cfc04 |
glibc < 2.16: MT-Unsafe
|
|
Packit |
7cfc04 |
T}
|
|
Packit |
7cfc04 |
.TE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Before glibc 2.16, the
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
function uses a static variable that is not protected,
|
|
Packit |
7cfc04 |
so it is not thread-safe.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
Since glibc 2.16,
|
|
Packit |
7cfc04 |
.\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
|
|
Packit |
7cfc04 |
the
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
function uses a lock to protect the static variable, so it is thread-safe.
|
|
Packit |
7cfc04 |
.SH CONFORMING TO
|
|
Packit |
7cfc04 |
The functions
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.BR addseverity (3),
|
|
Packit |
7cfc04 |
and environment variables
|
|
Packit |
7cfc04 |
.B MSGVERB
|
|
Packit |
7cfc04 |
and
|
|
Packit |
7cfc04 |
.B SEV_LEVEL
|
|
Packit |
7cfc04 |
come from System V.
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The function
|
|
Packit |
7cfc04 |
.BR fmtmsg ()
|
|
Packit |
7cfc04 |
and the environment variable
|
|
Packit |
7cfc04 |
.B MSGVERB
|
|
Packit |
7cfc04 |
are described in POSIX.1-2001 and POSIX.1-2008.
|
|
Packit |
7cfc04 |
.SH NOTES
|
|
Packit |
7cfc04 |
System V and UnixWare man pages tell us that these functions
|
|
Packit |
7cfc04 |
have been replaced by "pfmt() and addsev()" or by "pfmt(),
|
|
Packit |
7cfc04 |
vpfmt(), lfmt(), and vlfmt()", and will be removed later.
|
|
Packit |
7cfc04 |
.SH EXAMPLE
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
#include <stdio.h>
|
|
Packit |
7cfc04 |
#include <stdlib.h>
|
|
Packit |
7cfc04 |
#include <fmtmsg.h>
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
int
|
|
Packit |
7cfc04 |
main(void)
|
|
Packit |
7cfc04 |
{
|
|
Packit |
7cfc04 |
long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
|
|
Packit |
7cfc04 |
int err;
|
|
Packit |
7cfc04 |
|
|
Packit |
7cfc04 |
err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
|
|
Packit |
7cfc04 |
"unknown mount option", "See mount(8).",
|
|
Packit |
7cfc04 |
"util\-linux:mount:017");
|
|
Packit |
7cfc04 |
switch (err) {
|
|
Packit |
7cfc04 |
case MM_OK:
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case MM_NOTOK:
|
|
Packit |
7cfc04 |
printf("Nothing printed\en");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case MM_NOMSG:
|
|
Packit |
7cfc04 |
printf("Nothing printed to stderr\en");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
case MM_NOCON:
|
|
Packit |
7cfc04 |
printf("No console output\en");
|
|
Packit |
7cfc04 |
break;
|
|
Packit |
7cfc04 |
default:
|
|
Packit |
7cfc04 |
printf("Unknown error from fmtmsg()\en");
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
exit(EXIT_SUCCESS);
|
|
Packit |
7cfc04 |
}
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
The output should be:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
util\-linux:mount: ERROR: unknown mount option
|
|
Packit |
7cfc04 |
TO FIX: See mount(8). util\-linux:mount:017
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
and after
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
MSGVERB=text:action; export MSGVERB
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
the output becomes:
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.in +4n
|
|
Packit |
7cfc04 |
.EX
|
|
Packit |
7cfc04 |
unknown mount option
|
|
Packit |
7cfc04 |
TO FIX: See mount(8).
|
|
Packit |
7cfc04 |
.EE
|
|
Packit |
7cfc04 |
.in
|
|
Packit |
7cfc04 |
.PP
|
|
Packit |
7cfc04 |
.SH SEE ALSO
|
|
Packit |
7cfc04 |
.BR addseverity (3),
|
|
Packit |
7cfc04 |
.BR perror (3)
|
|
Packit |
7cfc04 |
.SH COLOPHON
|
|
Packit |
7cfc04 |
This page is part of release 4.15 of the Linux
|
|
Packit |
7cfc04 |
.I man-pages
|
|
Packit |
7cfc04 |
project.
|
|
Packit |
7cfc04 |
A description of the project,
|
|
Packit |
7cfc04 |
information about reporting bugs,
|
|
Packit |
7cfc04 |
and the latest version of this page,
|
|
Packit |
7cfc04 |
can be found at
|
|
Packit |
7cfc04 |
\%https://www.kernel.org/doc/man\-pages/.
|