1 files changed, 249 insertions, 0 deletions
diff --git a/man-pages-posix-2017/man3p/fmtmsg.3p b/man-pages-posix-2017/man3p/fmtmsg.3p
new file mode 100644
index 0000000..3fe4f3b
--- /dev/null
+++ b/man-pages-posix-2017/man3p/fmtmsg.3p
@@ -0,0 +1,249 @@
+'\" et
+.TH FMTMSG "3P" 2017 "IEEE/The Open Group" "POSIX Programmer's Manual"
+.\"
+.SH PROLOG
+This manual page is part of the POSIX Programmer's Manual.
+The Linux implementation of this interface may differ (consult
+the corresponding Linux manual page for details of Linux behavior),
+or the interface may not be implemented on Linux.
+.\"
+.SH NAME
+fmtmsg
+\(em display a message in the specified format on standard
+error and/or a system console
+.SH SYNOPSIS
+.LP
+.nf
+#include <fmtmsg.h>
+.P
+int fmtmsg(long \fIclassification\fP, const char *\fIlabel\fP, int \fIseverity\fP,
+    const char *\fItext\fP, const char *\fIaction\fP, const char *\fItag\fP);
+.fi
+.SH DESCRIPTION
+The
+\fIfmtmsg\fR()
+function shall display messages in a specified format instead
+of the traditional
+\fIprintf\fR()
+function.
+.P
+Based on a message's classification component,
+\fIfmtmsg\fR()
+shall write a formatted message either to standard error, to the
+console, or to both.
+.P
+A formatted message consists of up to five components as defined
+below. The component \fIclassification\fR is not part of a message
+displayed to the user, but defines the source of the message and
+directs the display of the formatted message.
+.IP "\fIclassification\fP" 12
+Contains the sum of identifying values constructed from the constants
+defined below. Any one identifier from a subclass may be used in
+combination with a single identifier from a different subclass. Two or
+more identifiers from the same subclass should not be used together,
+with the exception of identifiers from the display subclass. (Both
+display subclass identifiers may be used so that messages can be
+displayed to both standard error and the system console.)
+.RS 12 
+.IP "\fBMajor Classifications\fP" 6
+.br
+Identifies the source of the condition. Identifiers are: MM_HARD
+(hardware), MM_SOFT (software), and MM_FIRM (firmware).
+.IP "\fBMessage Source Subclassifications\fP" 6
+.br
+Identifies the type of software in which the problem is detected.
+Identifiers are: MM_APPL (application), MM_UTIL (utility), and MM_OPSYS
+(operating system).
+.IP "\fBDisplay Subclassifications\fP" 6
+.br
+Indicates where the message is to be displayed. Identifiers are:
+MM_PRINT to display the message on the standard error stream,
+MM_CONSOLE to display the message on the system console. One or both
+identifiers may be used.
+.IP "\fBStatus Subclassifications\fP" 6
+.br
+Indicates whether the application can recover from the condition.
+Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV
+(non-recoverable).
+.P
+An additional identifier, MM_NULLMC, indicates that no classification
+component is supplied for the message.
+.RE
+.IP "\fIlabel\fP" 12
+Identifies the source of the message. The format is two fields
+separated by a
+<colon>.
+The first field is up to 10 bytes, the second is up to 14 bytes.
+.IP "\fIseverity\fP" 12
+Indicates the seriousness of the condition. Identifiers for the levels
+of \fIseverity\fR are:
+.RS 12 
+.IP MM_HALT 12
+Indicates that the application has encountered a severe fault and is
+halting. Produces the string
+.BR \(dqHALT\(dq .
+.IP MM_ERROR 12
+Indicates that the application has detected a fault. Produces the
+string
+.BR \(dqERROR\(dq .
+.IP MM_WARNING 12
+Indicates a condition that is out of the ordinary, that might be a
+problem, and should be watched. Produces the string
+.BR \(dqWARNING\(dq .
+.IP MM_INFO 12
+Provides information about a condition that is not in error. Produces
+the string
+.BR \(dqINFO\(dq .
+.IP MM_NOSEV 12
+Indicates that no severity level is supplied for the message.
+.RE
+.IP "\fItext\fP" 12
+Describes the error condition that produced the message. The character
+string is not limited to a specific size. If the character string is
+empty, then the text produced is unspecified.
+.IP "\fIaction\fP" 12
+Describes the first step to be taken in the error-recovery process.
+The
+\fIfmtmsg\fR()
+function precedes the action string with the prefix:
+.BR \(dqTO FIX:\(dq .
+The \fIaction\fR string is not limited to a specific size.
+.IP "\fItag\fP" 12
+An identifier that references on-line documentation for the message.
+Suggested usage is that \fItag\fR includes the \fIlabel\fR and a unique
+identifying number. A sample \fItag\fR is
+.BR \(dqXSI:cat:146\(dq .
+.P
+The
+.IR MSGVERB
+environment variable (for message verbosity) shall determine for
+\fIfmtmsg\fR()
+which message components it is to select when writing messages to
+standard error. The value of
+.IR MSGVERB
+shall be a
+<colon>-separated
+list of optional keywords. Valid keywords are: \fIlabel\fR,
+\fIseverity\fR, \fItext\fR, \fIaction\fR, and \fItag\fR. If
+.IR MSGVERB
+contains a keyword for a component and the component's value is not the
+component's null value,
+\fIfmtmsg\fR()
+shall include that component in the message when writing the message to
+standard error. If
+.IR MSGVERB
+does not include a keyword for a message component, that component
+shall not be included in the display of the message. The keywords may
+appear in any order. If
+.IR MSGVERB
+is not defined, if its value is the null string, if its value is not of
+the correct format, or if it contains keywords other than the valid
+ones listed above,
+\fIfmtmsg\fR()
+shall select all components.
+.P
+.IR MSGVERB
+shall determine which components are selected for display to standard
+error. All message components shall be included in console messages.
+.SH "RETURN VALUE"
+The
+\fIfmtmsg\fR()
+function shall return one of the following values:
+.IP MM_OK 12
+The function succeeded.
+.IP MM_NOTOK 12
+The function failed completely.
+.IP MM_NOMSG 12
+The function was unable to generate a message on standard error,
+but otherwise succeeded.
+.IP MM_NOCON 12
+The function was unable to generate a console message, but otherwise
+succeeded.
+.SH ERRORS
+None.
+.LP
+.IR "The following sections are informative."
+.SH EXAMPLES
+.IP " 1." 4
+The following example of
+\fIfmtmsg\fR():
+.RS 4 
+.sp
+.RS 4
+.nf
+
+fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option",
+"refer to cat in user\(aqs reference manual", "XSI:cat:001")
+.fi
+.P
+.RE
+.P
+produces a complete message in the specified message format:
+.sp
+.RS 4
+.nf
+
+XSI:cat: ERROR: illegal option
+TO FIX: refer to cat in user\(aqs reference manual XSI:cat:001
+.fi
+.P
+.RE
+.RE
+.IP " 2." 4
+When the environment variable
+.IR MSGVERB
+is set as follows:
+.RS 4 
+.sp
+.RS 4
+.nf
+
+MSGVERB=severity:text:action
+.fi
+.P
+.RE
+.P
+and Example 1 is used,
+\fIfmtmsg\fR()
+produces:
+.sp
+.RS 4
+.nf
+
+ERROR: illegal option
+TO FIX: refer to cat in user\(aqs reference manual
+.fi
+.P
+.RE
+.RE
+.SH "APPLICATION USAGE"
+One or more message components may be systematically omitted from
+messages generated by an application by using the null value of the
+argument for that component.
+.SH RATIONALE
+None.
+.SH "FUTURE DIRECTIONS"
+None.
+.SH "SEE ALSO"
+.IR "\fIfprintf\fR\^(\|)"
+.P
+The Base Definitions volume of POSIX.1\(hy2017,
+.IR "\fB<fmtmsg.h>\fP"
+.\"
+.SH COPYRIGHT
+Portions of this text are reprinted and reproduced in electronic form
+from IEEE Std 1003.1-2017, Standard for Information Technology
+-- Portable Operating System Interface (POSIX), The Open Group Base
+Specifications Issue 7, 2018 Edition,
+Copyright (C) 2018 by the Institute of
+Electrical and Electronics Engineers, Inc and The Open Group.
+In the event of any discrepancy between this version and the original IEEE and
+The Open Group Standard, the original IEEE and The Open Group Standard
+is the referee document. The original Standard can be obtained online at
+http://www.opengroup.org/unix/online.html .
+.PP
+Any typographical or formatting errors that appear
+in this page are most likely
+to have been introduced during the conversion of the source files to
+man page format. To report such errors, see
+https://www.kernel.org/doc/man-pages/reporting_bugs.html .