1lfmt(3C) Standard C Library Functions lfmt(3C)
2
3
4
6 lfmt - display error message in standard format and pass to logging and
7 monitoring services
8
10 #include <pfmt.h>
11
12 int lfmt(FILE *stream, long flags, char *format, ... /* arg*/);
13
14
16 The lfmt() function retrieves a format string from a locale-specific
17 message database (unless MM_NOGET is specified) and uses it for
18 printf(3C) style formatting of args. The output is displayed on stream.
19 If stream is NULL no output is displayed.
20
21
22 The lfmt() function encapsulates the output in the standard error mes‐
23 sage format (unless MM_NOSTD is specified, in which case the output is
24 like that of printf(). It forwards its output to the logging and moni‐
25 toring facility, even if stream is NULL. Optionally, lfmt() displays
26 the output on the console with a date and time stamp.
27
28
29 If the printf() format string is to be retrieved from a message data‐
30 base, the format argument must have the following structure:
31
32
33 <catalog>:<msgnum>:<defmsg>.
34
35
36 If MM_NOGET is specified, only the <defmsg> field must be specified.
37
38
39 The <catalog> field indicates the message database that contains the
40 localized version of the format string. This field is limited to 14
41 characters selected from a set of all characters values, excluding the
42 null character (\0) and the ASCII codes for slash (/) and colon (:).
43
44
45 The <msgnum> field is a positive number that indicates the index of the
46 string into the message database.
47
48
49 If the catalog does not exist in the locale (specified by the last call
50 to setlocale(3C) using the LC_ALL or LC_MESSAGES categories), or if
51 the message number is out of bound, lfmt() will attempt to retrieve the
52 message from the C locale. If this second retrieval fails, lfmt() uses
53 the <defmsg> field of the format argument.
54
55
56 If <catalog> is omitted, lfmt() will attempt to retrieve the string
57 from the default catalog specified by the last call to setcat(3C). In
58 this case, the format argument has the following structure:
59
60
61 :<msgnum>:<defmsg>.
62
63
64 The lfmt() function will output the message
65
66
67 Message not found!!\n
68
69
70 as the format string if <catalog> is not a valid catalog name, if no
71 catalog is specified (either explicitly or with setcat()), if <msgnum>
72 is not a valid number, or if no message could be retrieved from the
73 message databases and <defmsg> was omitted.
74
75
76 The flags argument determines the type of output (whether the format
77 should be interpreted as it is or be encapsulated in the standard mes‐
78 sage format) and the access to message catalogs to retrieve a localized
79 version of format.
80
81
82 The flags argument is composed of several groups, and can take the fol‐
83 lowing values (one from each group):
84
85 Output format control
86
87
88 MM_NOSTD Do not use the standard message format but interpret
89 format as a printf() format. Only catalog access con‐
90 trol flags, console display control and logging infor‐
91 mation should be specified if MM_NOSTD is used; all
92 other flags will be ignored.
93
94
95 MM_STD Output using the standard message format (default value
96 is 0).
97
98
99
100 Catalog access control
101
102
103 MM_NOGET Do not retrieve a localized version of format. In this
104 case, only the <defmsg> field of format is specified.
105
106
107 MM_GET Retrieve a localized version of format from <catalog>,
108 using <msgid> as the index and <defmsg> as the default
109 message (default value is 0).
110
111
112
113 Severity (standard message format only)
114
115
116 MM_HALT Generate a localized version of HALT, but donot halt
117 the machine.
118
119
120 MM_ERROR Generate a localized version of ERROR (default value
121 is 0).
122
123
124 MM_WARNING Generate a localized version of WARNING.
125
126
127 MM_INFO Generate a localized version of INFO.
128
129 Additional severities can be defined with the addsev(3C) function,
130 using number-string pairs with numeric values in the range [5-255].
131 The specified severity is formed by the bitwise OR operation of the
132 numeric value and other flags arguments.
133
134 If the severity is not defined, lfmt() uses the string SEV=N where
135 N is the integer severity value passed in flags.
136
137 Multiple severities passed in flags will not be detected as an
138 error. Any combination of severities will be summed and the numeric
139 value will cause the display of either a severity string (if
140 defined) or the string SEV=N (if undefined).
141
142
143 Action
144
145
146 MM_ACTION Specify an action message. Any severity value is
147 superseded and replaced by a localized version of TO
148 FIX.
149
150
151
152 Console display control
153
154
155 MM_CONSOLE Display the message to the console in addition to
156 the specified stream.
157
158
159 MM_NOCONSOLE Do not display the message to the console in addi‐
160 tion to the specified stream (default value is 0).
161
162
163
164 Logging information
165
166
167 Major classification
168
169 Identify the source of the condition. Identifiers are: MM_HARD
170 (hardware), MM_SOFT (software), and MM_FIRM (firmware).
171
172
173 Message source subclassification
174
175 Identify the type of software in which the problem is spotted.
176 Identifiers are: MM_APPL (application), MM_UTIL (utility), and
177 MM_OPSYS (operating system).
178
179
180
182 The lfmt() function displays error messages in the following format:
183
184 label: severity: text
185
186
187
188 If no label was defined by a call to setlabel(3C), the message is dis‐
189 played in the format:
190
191 severity: text
192
193
194
195 If lfmt() is called twice to display an error message and a helpful
196 action or recovery message, the output may appear as follows:
197
198 label: severity: text
199 label: TO FIX: text
200
201
203 Upon successful completion, lfmt() returns the number of bytes trans‐
204 mitted. Otherwise, it returns a negative value:
205
206 −1 Write the error to stream.
207
208
209 −2 Cannot log and/or display at console.
210
211
213 Since lfmt() uses gettxt(3C), it is recommended that lfmt() not be
214 used.
215
217 Example 1 The following example
218
219 setlabel("UX:test");
220 lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
221 "test:2:Cannot open file: %s\n", strerror(errno));
222
223
224
225 displays the message to stderr and to the console and makes it avail‐
226 able for logging:
227
228
229 UX:test: ERROR: Cannot open file: No such file or directory
230
231
232 Example 2 The following example
233
234 setlabel("UX:test");
235 lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
236 "test:23:test facility is enabled\n");
237
238
239
240 displays the message to stderr and makes it available for logging:
241
242
243 UX:test: INFO: test facility enabled
244
245
247 See attributes(5) for descriptions of the following attributes:
248
249
250
251
252 ┌─────────────────────────────┬─────────────────────────────┐
253 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
254 ├─────────────────────────────┼─────────────────────────────┤
255 │MT-Level │MT-Safe │
256 └─────────────────────────────┴─────────────────────────────┘
257
259 addsev(3C), gettxt(3C), pfmt(3C), printf(3C), setcat(3C), setlabel(3C),
260 setlocale(3C), attributes(5), environ(5)
261
262
263
264SunOS 5.11 29 Dec 1996 lfmt(3C)