mirror of https://github.com/mkerrisk/man-pages
257 lines
7.4 KiB
Plaintext
257 lines
7.4 KiB
Plaintext
.\" Copyright (c) 2001-2003 The Open Group, All Rights Reserved
|
|
.TH "FMTMSG" 3P 2003 "IEEE/The Open Group" "POSIX Programmer's Manual"
|
|
.\" fmtmsg
|
|
.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 \- display a message in the specified format on standard error
|
|
and/or a system console
|
|
.SH SYNOPSIS
|
|
.LP
|
|
\fB#include <fmtmsg.h>
|
|
.br
|
|
.sp
|
|
int fmtmsg(long\fP \fIclassification\fP\fB, const char *\fP\fIlabel\fP\fB,
|
|
int\fP \fIseverity\fP\fB,
|
|
.br
|
|
\ \ \ \ \ \ const char *\fP\fItext\fP\fB, const char *\fP\fIaction\fP\fB,
|
|
const char
|
|
*\fP\fItag\fP\fB); \fP
|
|
\fB
|
|
.br
|
|
\fP
|
|
.SH DESCRIPTION
|
|
.LP
|
|
The \fIfmtmsg\fP() function shall display messages in a specified
|
|
format instead of the traditional \fIprintf\fP() function.
|
|
.LP
|
|
Based on a message's classification component, \fIfmtmsg\fP() shall
|
|
write a formatted message either to standard error, to the
|
|
console, or to both.
|
|
.LP
|
|
A formatted message consists of up to five components as defined below.
|
|
The component \fIclassification\fP 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.
|
|
.TP 7
|
|
\fIclassification\fP
|
|
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.)
|
|
.TP 7
|
|
\fBMajor Classifications\fP
|
|
.RS
|
|
.sp
|
|
Identifies the source of the condition. Identifiers are: MM_HARD (hardware),
|
|
MM_SOFT (software), and MM_FIRM (firmware).
|
|
.RE
|
|
.TP 7
|
|
\fBMessage Source Subclassifications\fP
|
|
.RS
|
|
.sp
|
|
Identifies the type of software in which the problem is detected.
|
|
Identifiers are: MM_APPL (application), MM_UTIL (utility), and
|
|
MM_OPSYS (operating system).
|
|
.RE
|
|
.TP 7
|
|
\fBDisplay Subclassifications\fP
|
|
.RS
|
|
.sp
|
|
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.
|
|
.RE
|
|
.TP 7
|
|
\fBStatus Subclassifications\fP
|
|
.RS
|
|
.sp
|
|
Indicates whether the application can recover from the condition.
|
|
Identifiers are: MM_RECOVER (recoverable) and MM_NRECOV
|
|
(non-recoverable).
|
|
.RE
|
|
.sp
|
|
.LP
|
|
An additional identifier, MM_NULLMC, indicates that no classification
|
|
component is supplied for the message.
|
|
.TP 7
|
|
\fIlabel\fP
|
|
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.
|
|
.TP 7
|
|
\fIseverity\fP
|
|
Indicates the seriousness of the condition. Identifiers for the levels
|
|
of \fIseverity\fP are:
|
|
.TP 7
|
|
MM_HALT
|
|
.RS
|
|
Indicates that the application has encountered a severe fault and
|
|
is halting. Produces the string \fB"HALT"\fP .
|
|
.RE
|
|
.TP 7
|
|
MM_ERROR
|
|
.RS
|
|
Indicates that the application has detected a fault. Produces the
|
|
string \fB"ERROR"\fP .
|
|
.RE
|
|
.TP 7
|
|
MM_WARNING
|
|
.RS
|
|
Indicates a condition that is out of the ordinary, that might be a
|
|
problem, and should be watched. Produces the string
|
|
\fB"WARNING"\fP .
|
|
.RE
|
|
.TP 7
|
|
MM_INFO
|
|
.RS
|
|
Provides information about a condition that is not in error. Produces
|
|
the string \fB"INFO"\fP .
|
|
.RE
|
|
.TP 7
|
|
MM_NOSEV
|
|
.RS
|
|
Indicates that no severity level is supplied for the message.
|
|
.RE
|
|
.sp
|
|
.TP 7
|
|
\fItext\fP
|
|
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.
|
|
.TP 7
|
|
\fIaction\fP
|
|
Describes the first step to be taken in the error-recovery process.
|
|
The \fIfmtmsg\fP() function precedes the action string
|
|
with the prefix: \fB"TO FIX:"\fP . The \fIaction\fP string is not
|
|
limited to a specific size.
|
|
.TP 7
|
|
\fItag\fP
|
|
An identifier that references on-line documentation for the message.
|
|
Suggested usage is that \fItag\fP includes the
|
|
\fIlabel\fP and a unique identifying number. A sample \fItag\fP is
|
|
\fB"XSI:cat:146"\fP .
|
|
.sp
|
|
.LP
|
|
The \fIMSGVERB\fP environment variable (for message verbosity) shall
|
|
determine for \fIfmtmsg\fP() which message components it
|
|
is to select when writing messages to standard error. The value of
|
|
\fIMSGVERB\fP shall be a colon-separated list of optional
|
|
keywords. Valid keywords are: \fIlabel\fP, \fIseverity\fP, \fItext\fP,
|
|
\fIaction\fP, and \fItag\fP. If \fIMSGVERB\fP contains
|
|
a keyword for a component and the component's value is not the component's
|
|
null value, \fIfmtmsg\fP() shall include that component
|
|
in the message when writing the message to standard error. If \fIMSGVERB\fP
|
|
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 \fIMSGVERB\fP 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\fP() shall select all components.
|
|
.LP
|
|
\fIMSGVERB\fP shall determine which components are selected for display
|
|
to standard error. All message components shall be
|
|
included in console messages.
|
|
.SH RETURN VALUE
|
|
.LP
|
|
The \fIfmtmsg\fP() function shall return one of the following values:
|
|
.TP 7
|
|
MM_OK
|
|
The function succeeded.
|
|
.TP 7
|
|
MM_NOTOK
|
|
The function failed completely.
|
|
.TP 7
|
|
MM_NOMSG
|
|
The function was unable to generate a message on standard error, but
|
|
otherwise succeeded.
|
|
.TP 7
|
|
MM_NOCON
|
|
The function was unable to generate a console message, but otherwise
|
|
succeeded.
|
|
.sp
|
|
.SH ERRORS
|
|
.LP
|
|
None.
|
|
.LP
|
|
\fIThe following sections are informative.\fP
|
|
.SH EXAMPLES
|
|
.IP " 1." 4
|
|
The following example of \fIfmtmsg\fP():
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBfmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option",
|
|
"refer to cat in user's reference manual", "XSI:cat:001")
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
produces a complete message in the specified message format:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBXSI:cat: ERROR: illegal option
|
|
TO FIX: refer to cat in user's reference manual XSI:cat:001
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.IP " 2." 4
|
|
When the environment variable \fIMSGVERB\fP is set as follows:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBMSGVERB=severity:text:action
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
and Example 1 is used, \fIfmtmsg\fP() produces:
|
|
.sp
|
|
.RS
|
|
.nf
|
|
|
|
\fBERROR: illegal option
|
|
TO FIX: refer to cat in user's reference manual
|
|
\fP
|
|
.fi
|
|
.RE
|
|
.LP
|
|
.SH APPLICATION USAGE
|
|
.LP
|
|
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
|
|
.LP
|
|
None.
|
|
.SH FUTURE DIRECTIONS
|
|
.LP
|
|
None.
|
|
.SH SEE ALSO
|
|
.LP
|
|
\fIprintf\fP(), the Base Definitions volume of IEEE\ Std\ 1003.1-2001,
|
|
\fI<fmtmsg.h>\fP
|
|
.SH COPYRIGHT
|
|
Portions of this text are reprinted and reproduced in electronic form
|
|
from IEEE Std 1003.1, 2003 Edition, Standard for Information Technology
|
|
-- Portable Operating System Interface (POSIX), The Open Group Base
|
|
Specifications Issue 6, Copyright (C) 2001-2003 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 .
|