summaryrefslogtreecommitdiffstats
path: root/man/man3/fmtmsg.3
diff options
context:
space:
mode:
authorDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
committerDaniel Baumann <daniel.baumann@progress-linux.org>2024-05-24 04:52:22 +0000
commit3d08cd331c1adcf0d917392f7e527b3f00511748 (patch)
tree312f0d1e1632f48862f044b8bb87e602dcffb5f9 /man/man3/fmtmsg.3
parentAdding debian version 6.7-2. (diff)
downloadmanpages-3d08cd331c1adcf0d917392f7e527b3f00511748.tar.xz
manpages-3d08cd331c1adcf0d917392f7e527b3f00511748.zip
Merging upstream version 6.8.
Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>
Diffstat (limited to 'man/man3/fmtmsg.3')
-rw-r--r--man/man3/fmtmsg.3337
1 files changed, 337 insertions, 0 deletions
diff --git a/man/man3/fmtmsg.3 b/man/man3/fmtmsg.3
new file mode 100644
index 0000000..b4fc2cc
--- /dev/null
+++ b/man/man3/fmtmsg.3
@@ -0,0 +1,337 @@
+'\" t
+.\" Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
+.\"
+.\" SPDX-License-Identifier: GPL-1.0-or-later
+.\"
+.\" adapted glibc info page
+.\"
+.\" This should run as 'Guru Meditation' (amiga joke :)
+.\" The function is quite complex and deserves an example
+.\"
+.\" Polished, aeb, 2003-11-01
+.TH fmtmsg 3 2024-05-02 "Linux man-pages (unreleased)"
+.SH NAME
+fmtmsg \- print formatted error messages
+.SH LIBRARY
+Standard C library
+.RI ( libc ", " \-lc )
+.SH SYNOPSIS
+.nf
+.B #include <fmtmsg.h>
+.P
+.BI "int fmtmsg(long " classification ", const char *" label ,
+.BI " int " severity ", const char *" text ,
+.BI " const char *" action ", const char *" tag );
+.fi
+.SH DESCRIPTION
+This function displays a message described by its arguments on the device(s)
+specified in the
+.I classification
+argument.
+For messages written to
+.IR stderr ,
+the format depends on the
+.B MSGVERB
+environment variable.
+.P
+The
+.I label
+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.
+.P
+The
+.I text
+argument describes the condition of the error.
+.P
+The
+.I action
+argument describes possible steps to recover from the error.
+If it is printed, it is prefixed by "TO FIX: ".
+.P
+The
+.I tag
+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 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
+.B NO_SEV
+(0) says that no severity is supplied.
+The values
+.BR MM_NULLLBL ,
+.BR MM_NULLTXT ,
+.BR MM_NULLACT ,
+.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 argument
+The
+.I classification
+argument is the sum of values describing 4 types of information.
+.P
+The first value defines the output channel.
+.TP 12n
+.B MM_PRINT
+Output to
+.IR stderr .
+.TP
+.B MM_CONSOLE
+Output to the system console.
+.TP
+.B "MM_PRINT | MM_CONSOLE"
+Output to both.
+.P
+The second value is the source of the error:
+.TP 12n
+.B MM_HARD
+A hardware error occurred.
+.TP
+.B MM_FIRM
+A firmware error occurred.
+.TP
+.B MM_SOFT
+A software error occurred.
+.P
+The third value encodes the detector of the problem:
+.TP 12n
+.B MM_APPL
+It is detected by an application.
+.TP
+.B MM_UTIL
+It is detected by a utility.
+.TP
+.B MM_OPSYS
+It is detected by the operating system.
+.P
+The fourth value shows the severity of the incident:
+.TP 12n
+.B MM_RECOVER
+It is a recoverable error.
+.TP
+.B MM_NRECOV
+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.
+.TP
+.B MM_HALT
+This value is printed as HALT.
+.TP
+.B MM_ERROR
+This value is printed as ERROR.
+.TP
+.B MM_WARNING
+This value is printed as WARNING.
+.TP
+.B MM_INFO
+This value is printed as INFO.
+.P
+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
+.B MSGVERB
+("message verbosity") can be used to suppress parts of
+the output to
+.IR stderr .
+(It does not influence output to the console.)
+When this variable is defined, is non-NULL, and is a colon-separated
+list of valid keywords, then only the parts of the message corresponding
+to these keywords is printed.
+Valid keywords are "label", "severity", "text", "action", and "tag".
+.P
+The environment variable
+.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
+.BR fmtmsg ()
+print nothing.
+If the user puts
+.B SEV_LEVEL
+with a format like
+.P
+.RS
+SEV_LEVEL=[description[:description[:...]]]
+.RE
+.P
+in the environment of the process before the first call to
+.BR fmtmsg (),
+where each description is of the form
+.P
+.RS
+severity-keyword,level,printstring
+.RE
+.P
+then
+.BR fmtmsg ()
+will also accept the indicated values for the level (in addition to
+the standard levels 0\[en]4), and use the indicated printstring when
+such a level occurs.
+.P
+The severity-keyword part is not used by
+.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 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
+.BR fmtmsg ().
+.SH ATTRIBUTES
+For an explanation of the terms used in this section, see
+.BR attributes (7).
+.TS
+allbox;
+lb lb lbx
+l l l.
+Interface Attribute Value
+T{
+.na
+.nh
+.BR fmtmsg ()
+T} Thread safety T{
+.na
+.nh
+glibc\ >=\ 2.16: MT-Safe;
+glibc\ <\ 2.16: MT-Unsafe
+T}
+.TE
+.P
+Before glibc 2.16, the
+.BR fmtmsg ()
+function uses a static variable that is not protected,
+so it is not thread-safe.
+.P
+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 STANDARDS
+.TP
+.BR fmtmsg ()
+.TQ
+.B MSGVERB
+POSIX.1-2008.
+.SH HISTORY
+.TP
+.BR fmtmsg ()
+System V.
+POSIX.1-2001 and POSIX.1-2008.
+glibc 2.1.
+.TP
+.B MSGVERB
+System V.
+POSIX.1-2001 and POSIX.1-2008.
+.TP
+.B SEV_LEVEL
+System V.
+.P
+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 EXAMPLES
+.\" SRC BEGIN (fmtmsg.c)
+.EX
+#include <fmtmsg.h>
+#include <stdio.h>
+#include <stdlib.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\en");
+ break;
+ case MM_NOMSG:
+ printf("Nothing printed to stderr\en");
+ break;
+ case MM_NOCON:
+ printf("No console output\en");
+ break;
+ default:
+ printf("Unknown error from fmtmsg()\en");
+ }
+ exit(EXIT_SUCCESS);
+}
+.EE
+.\" SRC END
+.P
+The output should be:
+.P
+.in +4n
+.EX
+util\-linux:mount: ERROR: unknown mount option
+TO FIX: See mount(8). util\-linux:mount:017
+.EE
+.in
+.P
+and after
+.P
+.in +4n
+.EX
+MSGVERB=text:action; export MSGVERB
+.EE
+.in
+.P
+the output becomes:
+.P
+.in +4n
+.EX
+unknown mount option
+TO FIX: See mount(8).
+.EE
+.in
+.SH SEE ALSO
+.BR addseverity (3),
+.BR perror (3)