| blob | 3699c6b6b4fb7f82eb085e133daea6ff34182328 |
1 '\" te
2 .\" Copyright (c) 2007, Sun Microsystems, Inc. All Rights Reserved.
3 .\" Copyright 1989 AT&T
4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License"). You may not use this file except in compliance with the License.
5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing. See the License for the specific language governing permissions and limitations under the License.
6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE. If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
7 .TH LFMT 3C "Dec 29, 1996"
8 .SH NAME
9 lfmt \- display error message in standard format and pass to logging and
10 monitoring services
11 .SH SYNOPSIS
12 .LP
13 .nf
14 #include <pfmt.h>
16 \fBint\fR \fBlfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg\fR*/);
17 .fi
19 .SH DESCRIPTION
20 .sp
21 .LP
22 The \fBlfmt()\fR function retrieves a format string from a locale-specific
23 message database (unless \fBMM_NOGET\fR is specified) and uses it for
24 \fBprintf\fR(3C) style formatting of \fIargs\fR. The output is displayed on
25 \fIstream\fR. If \fIstream\fR is \fINULL\fR no output is displayed.
26 .sp
27 .LP
28 The \fBlfmt()\fR function encapsulates the output in the standard error message
29 format (unless \fBMM_NOSTD\fR is specified, in which case the output is like
30 that of \fBprintf()\fR. It forwards its output to the logging and monitoring
31 facility, even if \fIstream\fR is \fINULL\fR. Optionally, \fBlfmt()\fR
32 displays the output on the console with a date and time stamp.
33 .sp
34 .LP
35 If the \fBprintf()\fR format string is to be retrieved from a message database,
36 the \fBformat\fR argument must have the following structure:
37 .sp
38 .LP
39 \fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
40 .sp
41 .LP
42 If \fBMM_NOGET\fR is specified, only the \fI<defmsg>\fR field must be
43 specified.
44 .sp
45 .LP
46 The \fI<catalog>\fR field indicates the message database that contains the
47 localized version of the format string. This field is limited to 14 characters
48 selected from a set of all characters values, excluding the null character
49 (\fB\e0\fR) and the ASCII codes for slash (\fB/\fR) and colon (\fB:\fR).
50 .sp
51 .LP
52 The \fI<msgnum>\fR field is a positive number that indicates the index of the
53 string into the message database.
54 .sp
55 .LP
56 If the catalog does not exist in the locale (specified by the last call to
57 \fBsetlocale\fR(3C) using the \fBLC_ALL\fR or \fBLC_MESSAGES\fR categories),
58 or if the message number is out of bound, \fBlfmt()\fR will attempt to retrieve
59 the message from the C locale. If this second retrieval fails, \fBlfmt()\fR
60 uses the \fI<defmsg>\fR field of the \fBformat\fR argument.
61 .sp
62 .LP
63 If \fI<catalog>\fR is omitted, \fBlfmt()\fR will attempt to retrieve the string
64 from the default catalog specified by the last call to \fBsetcat\fR(3C). In
65 this case, the \fBformat\fR argument has the following structure:
66 .sp
67 .LP
68 \fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
69 .sp
70 .LP
71 The \fBlfmt()\fR function will output the message
72 .sp
73 .LP
74 \fBMessage not found!!\en\fR
75 .sp
76 .LP
77 as the format string if \fI<catalog>\fR is not a valid catalog name, if no
78 catalog is specified (either explicitly or with \fBsetcat()\fR), if
79 \fI<msgnum>\fR is not a valid number, or if no message could be retrieved from
80 the message databases and \fI<defmsg>\fR was omitted.
81 .sp
82 .LP
83 The \fIflags\fR argument determines the type of output (whether the
84 \fBformat\fR should be interpreted as it is or be encapsulated in the standard
85 message format) and the access to message catalogs to retrieve a localized
86 version of \fBformat\fR.
87 .sp
88 .LP
89 The \fIflags\fR argument is composed of several groups, and can take the
90 following values (one from each group):
91 .sp
92 .ne 2
93 .na
94 \fB\fIOutput format control\fR\fR
95 .ad
96 .sp .6
97 .RS 4n
98 .sp
99 .ne 2
100 .na
101 \fB\fBMM_NOSTD\fR\fR
102 .ad
103 .RS 12n
104 Do not use the standard message format but interpret \fBformat\fR as a
105 \fBprintf()\fR \fBformat\fR. Only \fIcatalog access control flags\fR,
106 \fIconsole display control\fR and \fIlogging information\fR should be specified
107 if \fBMM_NOSTD\fR is used; all other flags will be ignored.
108 .RE
110 .sp
111 .ne 2
112 .na
113 \fB\fBMM_STD\fR\fR
114 .ad
115 .RS 12n
116 Output using the standard message format (default value is 0).
117 .RE
119 .RE
121 .sp
122 .ne 2
123 .na
124 \fB\fICatalog access control\fR\fR
125 .ad
126 .sp .6
127 .RS 4n
128 .sp
129 .ne 2
130 .na
131 \fB\fBMM_NOGET\fR\fR
132 .ad
133 .RS 12n
134 Do not retrieve a localized version of \fBformat\fR. In this case, only the
135 \fI<defmsg>\fR field of \fBformat\fR is specified.
136 .RE
138 .sp
139 .ne 2
140 .na
141 \fB\fBMM_GET\fR\fR
142 .ad
143 .RS 12n
144 Retrieve a localized version of \fBformat\fR from \fI<catalog>\fR, using
145 \fI<msgid>\fR as the index and \fI<defmsg>\fR as the default message (default
146 value is 0).
147 .RE
149 .RE
151 .sp
152 .ne 2
153 .na
154 \fB\fISeverity (standard message format only)\fR\fR
155 .ad
156 .sp .6
157 .RS 4n
158 .sp
159 .ne 2
160 .na
161 \fB\fBMM_HALT\fR\fR
162 .ad
163 .RS 14n
164 Generate a localized version of \fBHALT,\fR but donot halt the machine.
165 .RE
167 .sp
168 .ne 2
169 .na
170 \fB\fBMM_ERROR\fR\fR
171 .ad
172 .RS 14n
173 Generate a localized version of \fBERROR\fR (default value is 0).
174 .RE
176 .sp
177 .ne 2
178 .na
179 \fB\fBMM_WARNING\fR\fR
180 .ad
181 .RS 14n
182 Generate a localized version of \fBWARNING\fR.
183 .RE
185 .sp
186 .ne 2
187 .na
188 \fB\fBMM_INFO\fR\fR
189 .ad
190 .RS 14n
191 Generate a localized version of \fBINFO\fR.
192 .RE
194 Additional severities can be defined with the \fBaddsev\fR(3C) function, using
195 number-string pairs with numeric values in the range [5-255]. The specified
196 severity is formed by the bitwise \fBOR\fR operation of the numeric value and
197 other \fIflags\fR arguments.
198 .sp
199 If the severity is not defined, \fBlfmt()\fR uses the string \fBSEV=\fR\fIN\fR
200 where \fIN\fR is the integer severity value passed in \fIflags\fR.
201 .sp
202 Multiple severities passed in \fIflags\fR will not be detected as an error. Any
203 combination of severities will be summed and the numeric value will cause the
204 display of either a severity string (if defined) or the string
205 \fBSEV=\fR\fIN\fR (if undefined).
206 .RE
208 .sp
209 .ne 2
210 .na
211 \fB\fIAction\fR\fR
212 .ad
213 .sp .6
214 .RS 4n
215 .sp
216 .ne 2
217 .na
218 \fB\fBMM_ACTION\fR\fR
219 .ad
220 .RS 13n
221 Specify an action message. Any severity value is superseded and replaced by a
222 localized version of \fBTO FIX\fR.
223 .RE
225 .RE
227 .sp
228 .ne 2
229 .na
230 \fB\fIConsole display control\fR\fR
231 .ad
232 .sp .6
233 .RS 4n
234 .sp
235 .ne 2
236 .na
237 \fB\fBMM_CONSOLE\fR\fR
238 .ad
239 .RS 16n
240 Display the message to the console in addition to the specified \fIstream\fR.
241 .RE
243 .sp
244 .ne 2
245 .na
246 \fB\fBMM_NOCONSOLE\fR\fR
247 .ad
248 .RS 16n
249 Do not display the message to the console in addition to the specified
250 \fIstream\fR (default value is 0).
251 .RE
253 .RE
255 .sp
256 .ne 2
257 .na
258 \fB\fILogging information\fR\fR
259 .ad
260 .sp .6
261 .RS 4n
262 .sp
263 .ne 2
264 .na
265 \fB\fIMajor classification\fR\fR
266 .ad
267 .sp .6
268 .RS 4n
269 Identify the source of the condition. Identifiers are: \fBMM_HARD\fR
270 (hardware), \fBMM_SOFT\fR (software), and \fBMM_FIRM\fR (firmware).
271 .RE
273 .sp
274 .ne 2
275 .na
276 \fB\fIMessage source subclassification\fR\fR
277 .ad
278 .sp .6
279 .RS 4n
280 Identify the type of software in which the problem is spotted. Identifiers are:
281 \fBMM_APPL\fR (application), \fBMM_UTIL\fR (utility), and \fBMM_OPSYS\fR
282 (operating system).
283 .RE
285 .RE
287 .SH STANDARD ERROR MESSAGE FORMAT
288 .sp
289 .LP
290 The \fBlfmt()\fR function displays error messages in the following format:
291 .sp
292 .in +2
293 .nf
294 \fIlabel\fR\fB:\fR \fIseverity\fR\fB:\fR \fItext\fR
295 .fi
296 .in -2
298 .sp
299 .LP
300 If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is
301 displayed in the format:
302 .sp
303 .in +2
304 .nf
305 \fIseverity\fR\fB:\fR \fItext\fR
306 .fi
307 .in -2
309 .sp
310 .LP
311 If \fBlfmt()\fR is called twice to display an error message and a helpful
312 \fIaction\fR or recovery message, the output may appear as follows:
313 .sp
314 .in +2
315 .nf
316 \fIlabel\fR\fB: \fR\fIseverity\fR\fB: \fR\fItext\fR
317 \fIlabel\fR\fB: \fR \fBTO FIX:\fR \fItext\fR
318 .fi
319 .in -2
321 .SH RETURN VALUES
322 .sp
323 .LP
324 Upon successful completion, \fBlfmt()\fR returns the number of bytes
325 transmitted. Otherwise, it returns a negative value:
326 .sp
327 .ne 2
328 .na
329 \fB\fB\(mi1\fR\fR
330 .ad
331 .RS 9n
332 Write the error to \fIstream\fR.
333 .RE
335 .sp
336 .ne 2
337 .na
338 \fB\fB\(mi2\fR\fR
339 .ad
340 .RS 9n
341 Cannot log and/or display at console.
342 .RE
344 .SH USAGE
345 .sp
346 .LP
347 Since \fBlfmt()\fR uses \fBgettxt\fR(3C), it is recommended that \fBlfmt()\fR
348 not be used.
349 .SH EXAMPLES
350 .LP
351 \fBExample 1 \fRThe following example
352 .sp
353 .in +2
354 .nf
355 setlabel("UX:test");
356 lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
357 "test:2:Cannot open file: %s\en", strerror(errno));
358 .fi
359 .in -2
361 .sp
362 .LP
363 displays the message to \fBstderr\fR and to the console and makes it available
364 for logging:
366 .sp
367 .in +2
368 .nf
369 UX:test: ERROR: Cannot open file: No such file or directory
370 .fi
371 .in -2
373 .LP
374 \fBExample 2 \fRThe following example
375 .sp
376 .in +2
377 .nf
378 setlabel("UX:test");
379 lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
380 "test:23:test facility is enabled\en");
381 .fi
382 .in -2
384 .sp
385 .LP
386 displays the message to \fBstderr\fR and makes it available for logging:
388 .sp
389 .in +2
390 .nf
391 UX:test: INFO: test facility enabled
392 .fi
393 .in -2
395 .SH ATTRIBUTES
396 .sp
397 .LP
398 See \fBattributes\fR(5) for descriptions of the following attributes:
399 .sp
401 .sp
402 .TS
403 box;
404 c | c
405 l | l .
406 ATTRIBUTE TYPE ATTRIBUTE VALUE
407 _
408 MT-Level MT-Safe
409 .TE
411 .SH SEE ALSO
412 .sp
413 .LP
414 \fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBpfmt\fR(3C), \fBprintf\fR(3C),
415 \fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
416 \fBenviron\fR(5)