1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH PFMT 3C "Dec 29, 1996"
7 .SH NAME
8 pfmt \- display error message in standard format
9 .SH SYNOPSIS
10 .LP
11 .nf
12 #include <pfmt.h>
13
14 \fBint\fR \fBpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg */\fR);
15 .fi
16
17 .SH DESCRIPTION
18 .sp
19 .LP
20 The \fBpfmt()\fR retrieves a format string from a locale-specific message
21 database (unless \fBMM_NOGET\fR is specified) and uses it for \fBprintf\fR(3C)
22 style formatting of \fIargs\fR. The output is displayed on \fIstream\fR.
23 .sp
24 .LP
25 The \fBpfmt()\fR function encapsulates the output in the standard error message
26 format (unless \fBMM_NOSTD\fR is specified, in which case the output is similar
27 to \fBprintf()\fR).
28 .sp
29 .LP
30 If the \fBprintf()\fR format string is to be retrieved from a message database,
31 the \fBformat\fR argument must have the following structure:
32 .sp
33 .LP
34 \fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
35 .sp
36 .LP
37 If \fBMM_NOGET\fR is specified, only the \fIdefmsg\fR field must be specified.
38 .sp
39 .LP
174 .sp
175 .LP
176 Multiple severities passed in \fIflags\fR will not be detected as an error. Any
177 combination of severities will be summed and the numeric value will cause the
178 display of either a severity string (if defined) or the string
179 \fBSEV=\fR\fIN\fR (if undefined).
180 .sp
181 .LP
182 \fIAction\fR
183 .sp
184 .ne 2
185 .na
186 \fB\fBMM_ACTION\fR\fR
187 .ad
188 .RS 13n
189 Specify an action message. Any severity value is superseded and replaced by a
190 localized version of \fBTO FIX\fR.
191 .RE
192
193 .SH STANDARD ERROR MESSAGE FORMAT
194 .sp
195 .LP
196 The \fBpfmt()\fR function displays error messages in the following format:
197 .sp
198 .in +2
199 .nf
200 \fIlabel\fR: \fIseverity\fR: \fItext\fR
201 .fi
202 .in -2
203
204 .sp
205 .LP
206 If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is
207 displayed in the format:
208 .sp
209 .in +2
210 .nf
211 \fIseverity\fR: \fItext\fR
212 .fi
213 .in -2
214
215 .sp
216 .LP
217 If \fBpfmt()\fR is called twice to display an error message and a helpful
218 \fIaction\fR or recovery message, the output can look like:
219 .sp
220 .in +2
221 .nf
222 \fIlabel\fR: \fIseverity\fR: \fItext\fR\fIlabel\fR: TO FIX: \fItext\fR
223 .fi
224 .in -2
225
226 .br
227 .in +2
228
229 .in -2
230 .br
231 .in +2
232
233 .in -2
234 .SH RETURN VALUES
235 .sp
236 .LP
237 Upon success, \fBpfmt()\fR returns the number of bytes transmitted. Upon
238 failure, it returns a negative value:
239 .sp
240 .ne 2
241 .na
242 \fB\fB\(mi1\fR\fR
243 .ad
244 .RS 9n
245 Write error to \fIstream\fR.
246 .RE
247
248 .SH EXAMPLES
249 .LP
250 \fBExample 1 \fRExample of \fBpfmt()\fR function.
251 .sp
252 .LP
253 Example 1:
254
255 .sp
256 .in +2
257 .nf
258 setlabel("UX:test");
259 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\en",
260 strerror(errno));
261
262 displays the message:
263
264 UX:test: ERROR: Cannot open file: No such file or directory
265 .fi
266 .in -2
267
268 .sp
269 .LP
275 setlabel("UX:test");
276 setcat("test");
277 pfmt(stderr, MM_ERROR, ":10:Syntax error\en");
278 pfmt(stderr, MM_ACTION, "55:Usage ...\en");
279 .fi
280 .in -2
281
282 .sp
283 .LP
284 displays the message
285
286 .sp
287 .in +2
288 .nf
289 UX:test: ERROR: Syntax error
290 UX:test: TO FIX: Usage ...
291 .fi
292 .in -2
293
294 .SH USAGE
295 .sp
296 .LP
297 Since it uses \fBgettxt\fR(3C), \fBpfmt()\fR should not be used.
298 .SH ATTRIBUTES
299 .sp
300 .LP
301 See \fBattributes\fR(5) for descriptions of the following attributes:
302 .sp
303
304 .sp
305 .TS
306 box;
307 c | c
308 l | l .
309 ATTRIBUTE TYPE ATTRIBUTE VALUE
310 _
311 MT-Level MT-safe
312 .TE
313
314 .SH SEE ALSO
315 .sp
316 .LP
317 \fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBprintf\fR(3C),
318 \fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
319 \fBenviron\fR(5)
|
1 '\" te
2 .\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
3 .\" 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.
4 .\" 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.
5 .\" 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]
6 .TH PFMT 3C "Dec 29, 1996"
7 .SH NAME
8 pfmt \- display error message in standard format
9 .SH SYNOPSIS
10 .nf
11 #include <pfmt.h>
12
13 \fBint\fR \fBpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg */\fR);
14 .fi
15
16 .SH DESCRIPTION
17 The \fBpfmt()\fR retrieves a format string from a locale-specific message
18 database (unless \fBMM_NOGET\fR is specified) and uses it for \fBprintf\fR(3C)
19 style formatting of \fIargs\fR. The output is displayed on \fIstream\fR.
20 .sp
21 .LP
22 The \fBpfmt()\fR function encapsulates the output in the standard error message
23 format (unless \fBMM_NOSTD\fR is specified, in which case the output is similar
24 to \fBprintf()\fR).
25 .sp
26 .LP
27 If the \fBprintf()\fR format string is to be retrieved from a message database,
28 the \fBformat\fR argument must have the following structure:
29 .sp
30 .LP
31 \fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
32 .sp
33 .LP
34 If \fBMM_NOGET\fR is specified, only the \fIdefmsg\fR field must be specified.
35 .sp
36 .LP
171 .sp
172 .LP
173 Multiple severities passed in \fIflags\fR will not be detected as an error. Any
174 combination of severities will be summed and the numeric value will cause the
175 display of either a severity string (if defined) or the string
176 \fBSEV=\fR\fIN\fR (if undefined).
177 .sp
178 .LP
179 \fIAction\fR
180 .sp
181 .ne 2
182 .na
183 \fB\fBMM_ACTION\fR\fR
184 .ad
185 .RS 13n
186 Specify an action message. Any severity value is superseded and replaced by a
187 localized version of \fBTO FIX\fR.
188 .RE
189
190 .SH STANDARD ERROR MESSAGE FORMAT
191 The \fBpfmt()\fR function displays error messages in the following format:
192 .sp
193 .in +2
194 .nf
195 \fIlabel\fR: \fIseverity\fR: \fItext\fR
196 .fi
197 .in -2
198
199 .sp
200 .LP
201 If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is
202 displayed in the format:
203 .sp
204 .in +2
205 .nf
206 \fIseverity\fR: \fItext\fR
207 .fi
208 .in -2
209
210 .sp
211 .LP
212 If \fBpfmt()\fR is called twice to display an error message and a helpful
213 \fIaction\fR or recovery message, the output can look like:
214 .sp
215 .in +2
216 .nf
217 \fIlabel\fR: \fIseverity\fR: \fItext\fR\fIlabel\fR: TO FIX: \fItext\fR
218 .fi
219 .in -2
220
221 .SH RETURN VALUES
222 Upon success, \fBpfmt()\fR returns the number of bytes transmitted. Upon
223 failure, it returns a negative value:
224 .sp
225 .ne 2
226 .na
227 \fB\fB\(mi1\fR\fR
228 .ad
229 .RS 9n
230 Write error to \fIstream\fR.
231 .RE
232
233 .SH EXAMPLES
234 \fBExample 1 \fRExample of \fBpfmt()\fR function.
235 .sp
236 .LP
237 Example 1:
238
239 .sp
240 .in +2
241 .nf
242 setlabel("UX:test");
243 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\en",
244 strerror(errno));
245
246 displays the message:
247
248 UX:test: ERROR: Cannot open file: No such file or directory
249 .fi
250 .in -2
251
252 .sp
253 .LP
259 setlabel("UX:test");
260 setcat("test");
261 pfmt(stderr, MM_ERROR, ":10:Syntax error\en");
262 pfmt(stderr, MM_ACTION, "55:Usage ...\en");
263 .fi
264 .in -2
265
266 .sp
267 .LP
268 displays the message
269
270 .sp
271 .in +2
272 .nf
273 UX:test: ERROR: Syntax error
274 UX:test: TO FIX: Usage ...
275 .fi
276 .in -2
277
278 .SH USAGE
279 Since it uses \fBgettxt\fR(3C), \fBpfmt()\fR should not be used.
280 .SH ATTRIBUTES
281 See \fBattributes\fR(5) for descriptions of the following attributes:
282 .sp
283
284 .sp
285 .TS
286 box;
287 c | c
288 l | l .
289 ATTRIBUTE TYPE ATTRIBUTE VALUE
290 _
291 MT-Level MT-safe
292 .TE
293
294 .SH SEE ALSO
295 \fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBprintf\fR(3C),
296 \fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
297 \fBenviron\fR(5)
|