Merging upstream version 6.8.

Signed-off-by: Daniel Baumann <daniel.baumann@progress-linux.org>

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)