1FMTMSG(3P)                 POSIX Programmer's Manual                FMTMSG(3P)
2
3
4

PROLOG

6       This  manual  page is part of the POSIX Programmer's Manual.  The Linux
7       implementation of this interface may differ (consult the  corresponding
8       Linux  manual page for details of Linux behavior), or the interface may
9       not be implemented on Linux.
10

NAME

12       fmtmsg — display a message in the specified format  on  standard  error
13       and/or a system console
14

SYNOPSIS

16       #include <fmtmsg.h>
17
18       int fmtmsg(long classification, const char *label, int severity,
19           const char *text, const char *action, const char *tag);
20

DESCRIPTION

22       The  fmtmsg()  function  shall  display  messages in a specified format
23       instead of the traditional printf() function.
24
25       Based on a message's classification component, fmtmsg() shall  write  a
26       formatted message either to standard error, to the console, or to both.
27
28       A formatted message consists of up to five components as defined below.
29       The component classification is not part of a message displayed to  the
30       user,  but defines the source of the message and directs the display of
31       the formatted message.
32
33       classification
34                   Contains the sum of identifying values constructed from the
35                   constants defined below. Any one identifier from a subclass
36                   may be used in combination with a single identifier from  a
37                   different  subclass.  Two or more identifiers from the same
38                   subclass should not be used together, with the exception of
39                   identifiers  from  the display subclass. (Both display sub‐
40                   class identifiers may be used so that messages can be  dis‐
41                   played to both standard error and the system console.)
42
43                   Major Classifications
44                         Identifies  the  source of the condition. Identifiers
45                         are:  MM_HARD  (hardware),  MM_SOFT  (software),  and
46                         MM_FIRM (firmware).
47
48                   Message Source Subclassifications
49                         Identifies  the type of software in which the problem
50                         is detected.  Identifiers are: MM_APPL (application),
51                         MM_UTIL (utility), and MM_OPSYS (operating system).
52
53                   Display Subclassifications
54                         Indicates where the message is to be displayed. Iden‐
55                         tifiers are: MM_PRINT to display the message  on  the
56                         standard error stream, MM_CONSOLE to display the mes‐
57                         sage on the system console. One or  both  identifiers
58                         may be used.
59
60                   Status Subclassifications
61                         Indicates  whether  the  application can recover from
62                         the condition.  Identifiers are: MM_RECOVER (recover‐
63                         able) and MM_NRECOV (non-recoverable).
64
65                   An  additional  identifier,  MM_NULLMC,  indicates  that no
66                   classification component is supplied for the message.
67
68       label       Identifies the source of the message.  The  format  is  two
69                   fields separated by a <colon>.  The first field is up to 10
70                   bytes, the second is up to 14 bytes.
71
72       severity    Indicates the seriousness of the condition. Identifiers for
73                   the levels of severity are:
74
75                   MM_HALT     Indicates  that the application has encountered
76                               a severe fault and  is  halting.  Produces  the
77                               string "HALT".
78
79                   MM_ERROR    Indicates  that  the application has detected a
80                               fault. Produces the string "ERROR".
81
82                   MM_WARNING  Indicates a condition that is out of the  ordi‐
83                               nary,  that  might  be a problem, and should be
84                               watched. Produces the string "WARNING".
85
86                   MM_INFO     Provides information about a condition that  is
87                               not in error. Produces the string "INFO".
88
89                   MM_NOSEV    Indicates  that  no  severity level is supplied
90                               for the message.
91
92       text        Describes the error condition that  produced  the  message.
93                   The  character string is not limited to a specific size. If
94                   the character string is empty, then the  text  produced  is
95                   unspecified.
96
97       action      Describes  the first step to be taken in the error-recovery
98                   process.  The fmtmsg() function precedes the action  string
99                   with  the  prefix: "TOFIX:".  The action string is not lim‐
100                   ited to a specific size.
101
102       tag         An identifier that references on-line documentation for the
103                   message.   Suggested  usage  is that tag includes the label
104                   and  a  unique  identifying  number.  A   sample   tag   is
105                   "XSI:cat:146".
106
107       The  MSGVERB  environment variable (for message verbosity) shall deter‐
108       mine for fmtmsg() which message components it is to select when writing
109       messages   to   standard  error.  The  value  of  MSGVERB  shall  be  a
110       <colon>-separated list of optional keywords. Valid keywords are: label,
111       severity,  text,  action,  and tag. If MSGVERB contains a keyword for a
112       component and the component's value is not the component's null  value,
113       fmtmsg()  shall  include that component in the message when writing the
114       message to standard error. If MSGVERB does not include a keyword for  a
115       message  component, that component shall not be included in the display
116       of the message. The keywords may appear in any order. If MSGVERB is not
117       defined,  if  its  value is the null string, if its value is not of the
118       correct format, or if it contains keywords other than  the  valid  ones
119       listed above, fmtmsg() shall select all components.
120
121       MSGVERB  shall  determine  which components are selected for display to
122       standard error. All message components shall  be  included  in  console
123       messages.
124

RETURN VALUE

126       The fmtmsg() function shall return one of the following values:
127
128       MM_OK       The function succeeded.
129
130       MM_NOTOK    The function failed completely.
131
132       MM_NOMSG    The  function  was unable to generate a message on standard
133                   error, but otherwise succeeded.
134
135       MM_NOCON    The function was unable to generate a console message,  but
136                   otherwise succeeded.
137

ERRORS

139       None.
140
141       The following sections are informative.
142

EXAMPLES

144        1. The following example of fmtmsg():
145
146
147               fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option",
148               "refer to cat in user's reference manual", "XSI:cat:001")
149
150           produces a complete message in the specified message format:
151
152
153               XSI:cat: ERROR: illegal option
154               TO FIX: refer to cat in user's reference manual XSI:cat:001
155
156        2. When the environment variable MSGVERB is set as follows:
157
158
159               MSGVERB=severity:text:action
160
161           and Example 1 is used, fmtmsg() produces:
162
163
164               ERROR: illegal option
165               TO FIX: refer to cat in user's reference manual
166

APPLICATION USAGE

168       One  or more message components may be systematically omitted from mes‐
169       sages generated by an application by using the null value of the  argu‐
170       ment for that component.
171

RATIONALE

173       None.
174

FUTURE DIRECTIONS

176       None.
177

SEE ALSO

179       fprintf()
180
181       The Base Definitions volume of POSIX.1‐2017, <fmtmsg.h>
182
184       Portions  of  this text are reprinted and reproduced in electronic form
185       from IEEE Std 1003.1-2017, Standard for Information Technology --  Por‐
186       table  Operating System Interface (POSIX), The Open Group Base Specifi‐
187       cations Issue 7, 2018 Edition, Copyright (C) 2018 by the  Institute  of
188       Electrical  and  Electronics Engineers, Inc and The Open Group.  In the
189       event of any discrepancy between this version and the original IEEE and
190       The  Open Group Standard, the original IEEE and The Open Group Standard
191       is the referee document. The original Standard can be  obtained  online
192       at http://www.opengroup.org/unix/online.html .
193
194       Any  typographical  or  formatting  errors that appear in this page are
195       most likely to have been introduced during the conversion of the source
196       files  to  man page format. To report such errors, see https://www.ker
197       nel.org/doc/man-pages/reporting_bugs.html .
198
199
200
201IEEE/The Open Group                  2017                           FMTMSG(3P)
Impressum