fmtmsg.3p (7683B)
- '\" 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 .