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