Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/pfmt.3c
+++ new/usr/src/man/man3c/pfmt.3c
1 1 '\" te
2 2 .\" Copyright 1989 AT&T Copyright (c) 1997, Sun Microsystems, Inc. All Rights Reserved
3 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 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 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 6 .TH PFMT 3C "Dec 29, 1996"
7 7 .SH NAME
8 8 pfmt \- display error message in standard format
9 9 .SH SYNOPSIS
10 -.LP
11 10 .nf
12 11 #include <pfmt.h>
13 12
14 13 \fBint\fR \fBpfmt\fR(\fBFILE *\fR\fIstream\fR, \fBlong\fR \fIflags\fR, \fBchar *\fR\fIformat\fR, \fB\&... /*\fR \fIarg */\fR);
15 14 .fi
16 15
17 16 .SH DESCRIPTION
18 -.sp
19 -.LP
20 17 The \fBpfmt()\fR retrieves a format string from a locale-specific message
21 18 database (unless \fBMM_NOGET\fR is specified) and uses it for \fBprintf\fR(3C)
22 19 style formatting of \fIargs\fR. The output is displayed on \fIstream\fR.
23 20 .sp
24 21 .LP
25 22 The \fBpfmt()\fR function encapsulates the output in the standard error message
26 23 format (unless \fBMM_NOSTD\fR is specified, in which case the output is similar
27 24 to \fBprintf()\fR).
28 25 .sp
29 26 .LP
30 27 If the \fBprintf()\fR format string is to be retrieved from a message database,
31 28 the \fBformat\fR argument must have the following structure:
32 29 .sp
33 30 .LP
34 31 \fI<catalog>\fR\fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
35 32 .sp
36 33 .LP
37 34 If \fBMM_NOGET\fR is specified, only the \fIdefmsg\fR field must be specified.
38 35 .sp
39 36 .LP
40 37 The \fIcatalog\fR field is used to indicate the message database that contains
41 38 the localized version of the format string. This field must be limited to 14
42 39 characters selected from the set of all characters values, excluding \fB\e0\fR
43 40 (null) and the ASCII codes for \fB/\fR (slash) and \fB:\fR (colon).
44 41 .sp
45 42 .LP
46 43 The \fImsgnum\fR field is a positive number that indicates the index of the
47 44 string into the message database.
48 45 .sp
49 46 .LP
50 47 If the catalog does not exist in the locale (specified by the last call to
51 48 \fBsetlocale\fR(3C) using the \fBLC_ALL\fR or \fBLC_MESSAGES\fR categories), or
52 49 if the message number is out of bound, \fBpfmt()\fR will attempt to retrieve
53 50 the message from the C locale. If this second retrieval fails, \fBpfmt()\fR
54 51 uses the \fIdefmsg\fR field of the \fBformat\fR argument.
55 52 .sp
56 53 .LP
57 54 If \fIcatalog\fR is omitted, \fBpfmt()\fR will attempt to retrieve the string
58 55 from the default catalog specified by the last call to \fBsetcat\fR(3C). In
59 56 this case, the \fBformat\fR argument has the following structure:
60 57 .sp
61 58 .LP
62 59 \fB:\fR\fI<msgnum>\fR\fB:\fR\fI<defmsg>\fR\&.
63 60 .sp
64 61 .LP
65 62 The \fBpfmt()\fR will output \fBMessage not found!!\en\fR as format string if
66 63 \fIcatalog\fR is not a valid catalog name, if no catalog is specified (either
67 64 explicitely or with \fBsetcat()\fR), if \fImsgnum\fR is not a valid number, or
68 65 if no message could be retrieved from the message databases and \fIdefmsg\fR
69 66 was omitted.
70 67 .sp
71 68 .LP
72 69 The \fIflags\fR argument determine the type of output (such as whether the
73 70 \fBformat\fR should be interpreted as is or encapsulated in the standard
74 71 message format), and the access to message catalogs to retrieve a localized
75 72 version of \fBformat\fR.
76 73 .sp
77 74 .LP
78 75 The \fIflags\fR argument is composed of several groups, and can take the
79 76 following values (one from each group):
80 77 .sp
81 78 .LP
82 79 \fIOutput format control\fR
83 80 .sp
84 81 .ne 2
85 82 .na
86 83 \fB\fBMM_NOSTD\fR\fR
87 84 .ad
88 85 .RS 12n
89 86 Do not use the standard message format, interpret \fBformat\fR as
90 87 \fBprintf()\fR \fBformat\fR. Only \fIcatalog access control flags\fR should be
91 88 specified if \fBMM_NOSTD\fR is used; all other flags will be ignored.
92 89 .RE
93 90
94 91 .sp
95 92 .ne 2
96 93 .na
97 94 \fB\fBMM_STD\fR\fR
98 95 .ad
99 96 .RS 12n
100 97 Output using the standard message format (default value 0).
101 98 .RE
102 99
103 100 .sp
104 101 .LP
105 102 \fICatalog access control\fR
106 103 .sp
107 104 .ne 2
108 105 .na
109 106 \fB\fBMM_NOGET\fR\fR
110 107 .ad
111 108 .RS 12n
112 109 Do not retrieve a localized version of \fBformat\fR. In this case, only the
113 110 \fIdefmsg\fR field of the \fBformat\fR is specified.
114 111 .RE
115 112
116 113 .sp
117 114 .ne 2
118 115 .na
119 116 \fB\fBMM_GET\fR\fR
120 117 .ad
121 118 .RS 12n
122 119 Retrieve a localized version of \fBformat\fR from the \fIcatalog\fR, using
123 120 \fImsgid\fR as the index and \fIdefmsg\fR as the default message (default value
124 121 0).
125 122 .RE
126 123
127 124 .sp
128 125 .LP
129 126 \fISeverity (standard message format only)\fR
130 127 .sp
131 128 .ne 2
132 129 .na
133 130 \fB\fBMM_HALT\fR\fR
134 131 .ad
135 132 .RS 14n
136 133 Generate a localized version of \fBHALT,\fR but do not halt the machine.
137 134 .RE
138 135
139 136 .sp
140 137 .ne 2
141 138 .na
142 139 \fB\fBMM_ERROR\fR\fR
143 140 .ad
144 141 .RS 14n
145 142 Generate a localized version of \fBERROR\fR (default value 0).
146 143 .RE
147 144
148 145 .sp
149 146 .ne 2
150 147 .na
151 148 \fB\fBMM_WARNING\fR\fR
152 149 .ad
153 150 .RS 14n
154 151 Generate a localized version of \fBWARNING.\fR
155 152 .RE
156 153
157 154 .sp
158 155 .ne 2
159 156 .na
160 157 \fB\fBMM_INFO\fR\fR
161 158 .ad
162 159 .RS 14n
163 160 Generate a localized version of \fBINFO.\fR
164 161 .RE
165 162
166 163 .sp
167 164 .LP
168 165 Additional severities can be defined. Add-on severities can be defined with
169 166 number-string pairs with numeric values from the range [5-255], using
170 167 \fBaddsev\fR(3C). The specified severity will be generated from the bitwise
171 168 \fBOR\fR operation of the numeric value and other \fIflags\fR If the severity
172 169 is not defined, \fBpfmt()\fR uses the string \fBSEV=\fR\fIN\fR, where \fIN\fR
173 170 is replaced by the integer severity value passed in \fIflags\fR.
174 171 .sp
175 172 .LP
176 173 Multiple severities passed in \fIflags\fR will not be detected as an error. Any
177 174 combination of severities will be summed and the numeric value will cause the
178 175 display of either a severity string (if defined) or the string
179 176 \fBSEV=\fR\fIN\fR (if undefined).
180 177 .sp
181 178 .LP
182 179 \fIAction\fR
183 180 .sp
|
↓ open down ↓ |
154 lines elided |
↑ open up ↑ |
184 181 .ne 2
185 182 .na
186 183 \fB\fBMM_ACTION\fR\fR
187 184 .ad
188 185 .RS 13n
189 186 Specify an action message. Any severity value is superseded and replaced by a
190 187 localized version of \fBTO FIX\fR.
191 188 .RE
192 189
193 190 .SH STANDARD ERROR MESSAGE FORMAT
194 -.sp
195 -.LP
196 191 The \fBpfmt()\fR function displays error messages in the following format:
197 192 .sp
198 193 .in +2
199 194 .nf
200 195 \fIlabel\fR: \fIseverity\fR: \fItext\fR
201 196 .fi
202 197 .in -2
203 198
204 199 .sp
205 200 .LP
206 201 If no \fIlabel\fR was defined by a call to \fBsetlabel\fR(3C), the message is
207 202 displayed in the format:
208 203 .sp
209 204 .in +2
210 205 .nf
211 206 \fIseverity\fR: \fItext\fR
212 207 .fi
213 208 .in -2
214 209
215 210 .sp
|
↓ open down ↓ |
10 lines elided |
↑ open up ↑ |
216 211 .LP
217 212 If \fBpfmt()\fR is called twice to display an error message and a helpful
218 213 \fIaction\fR or recovery message, the output can look like:
219 214 .sp
220 215 .in +2
221 216 .nf
222 217 \fIlabel\fR: \fIseverity\fR: \fItext\fR\fIlabel\fR: TO FIX: \fItext\fR
223 218 .fi
224 219 .in -2
225 220
226 -.br
227 -.in +2
228 -
229 -.in -2
230 -.br
231 -.in +2
232 -
233 -.in -2
234 221 .SH RETURN VALUES
235 -.sp
236 -.LP
237 222 Upon success, \fBpfmt()\fR returns the number of bytes transmitted. Upon
238 223 failure, it returns a negative value:
239 224 .sp
240 225 .ne 2
241 226 .na
242 227 \fB\fB\(mi1\fR\fR
243 228 .ad
244 229 .RS 9n
245 230 Write error to \fIstream\fR.
246 231 .RE
247 232
248 233 .SH EXAMPLES
249 -.LP
250 234 \fBExample 1 \fRExample of \fBpfmt()\fR function.
251 235 .sp
252 236 .LP
253 237 Example 1:
254 238
255 239 .sp
256 240 .in +2
257 241 .nf
258 242 setlabel("UX:test");
259 243 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\en",
260 244 strerror(errno));
261 245
262 246 displays the message:
263 247
264 248 UX:test: ERROR: Cannot open file: No such file or directory
265 249 .fi
266 250 .in -2
267 251
268 252 .sp
269 253 .LP
270 254 Example 2:
271 255
272 256 .sp
273 257 .in +2
274 258 .nf
275 259 setlabel("UX:test");
276 260 setcat("test");
277 261 pfmt(stderr, MM_ERROR, ":10:Syntax error\en");
278 262 pfmt(stderr, MM_ACTION, "55:Usage ...\en");
279 263 .fi
280 264 .in -2
281 265
282 266 .sp
283 267 .LP
284 268 displays the message
|
↓ open down ↓ |
25 lines elided |
↑ open up ↑ |
285 269
286 270 .sp
287 271 .in +2
288 272 .nf
289 273 UX:test: ERROR: Syntax error
290 274 UX:test: TO FIX: Usage ...
291 275 .fi
292 276 .in -2
293 277
294 278 .SH USAGE
295 -.sp
296 -.LP
297 279 Since it uses \fBgettxt\fR(3C), \fBpfmt()\fR should not be used.
298 280 .SH ATTRIBUTES
299 -.sp
300 -.LP
301 281 See \fBattributes\fR(5) for descriptions of the following attributes:
302 282 .sp
303 283
304 284 .sp
305 285 .TS
306 286 box;
307 287 c | c
308 288 l | l .
309 289 ATTRIBUTE TYPE ATTRIBUTE VALUE
310 290 _
311 291 MT-Level MT-safe
312 292 .TE
313 293
314 294 .SH SEE ALSO
315 -.sp
316 -.LP
317 295 \fBaddsev\fR(3C), \fBgettxt\fR(3C), \fBlfmt\fR(3C), \fBprintf\fR(3C),
318 296 \fBsetcat\fR(3C), \fBsetlabel\fR(3C), \fBsetlocale\fR(3C), \fBattributes\fR(5),
319 297 \fBenviron\fR(5)
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX