Print this page
11622 clean up rarer mandoc lint warnings
| Split |
Close |
| Expand all |
| Collapse all |
--- old/usr/src/man/man3c/pfmt.3c.man.txt
+++ new/usr/src/man/man3c/pfmt.3c.man.txt
1 1 PFMT(3C) Standard C Library Functions PFMT(3C)
2 2
3 3
4 4
5 5 NAME
6 6 pfmt - display error message in standard format
7 7
8 8 SYNOPSIS
9 9 #include <pfmt.h>
10 10
11 11 int pfmt(FILE *stream, long flags, char *format, ... /* arg */);
12 12
13 13
14 14 DESCRIPTION
15 15 The pfmt() retrieves a format string from a locale-specific message
16 16 database (unless MM_NOGET is specified) and uses it for printf(3C)
17 17 style formatting of args. The output is displayed on stream.
18 18
19 19
20 20 The pfmt() function encapsulates the output in the standard error
21 21 message format (unless MM_NOSTD is specified, in which case the output
22 22 is similar to printf()).
23 23
24 24
25 25 If the printf() format string is to be retrieved from a message
26 26 database, the format argument must have the following structure:
27 27
28 28
29 29 <catalog>:<msgnum>:<defmsg>.
30 30
31 31
32 32 If MM_NOGET is specified, only the defmsg field must be specified.
33 33
34 34
35 35 The catalog field is used to indicate the message database that
36 36 contains the localized version of the format string. This field must be
37 37 limited to 14 characters selected from the set of all characters
38 38 values, excluding \0 (null) and the ASCII codes for / (slash) and :
39 39 (colon).
40 40
41 41
42 42 The msgnum field is a positive number that indicates the index of the
43 43 string into the message database.
44 44
45 45
46 46 If the catalog does not exist in the locale (specified by the last call
47 47 to setlocale(3C) using the LC_ALL or LC_MESSAGES categories), or if the
48 48 message number is out of bound, pfmt() will attempt to retrieve the
49 49 message from the C locale. If this second retrieval fails, pfmt() uses
50 50 the defmsg field of the format argument.
51 51
52 52
53 53 If catalog is omitted, pfmt() will attempt to retrieve the string from
54 54 the default catalog specified by the last call to setcat(3C). In this
55 55 case, the format argument has the following structure:
56 56
57 57
58 58 :<msgnum>:<defmsg>.
59 59
60 60
61 61 The pfmt() will output Message not found!!\n as format string if
62 62 catalog is not a valid catalog name, if no catalog is specified (either
63 63 explicitely or with setcat()), if msgnum is not a valid number, or if
64 64 no message could be retrieved from the message databases and defmsg was
65 65 omitted.
66 66
67 67
68 68 The flags argument determine the type of output (such as whether the
69 69 format should be interpreted as is or encapsulated in the standard
70 70 message format), and the access to message catalogs to retrieve a
71 71 localized version of format.
72 72
73 73
74 74 The flags argument is composed of several groups, and can take the
75 75 following values (one from each group):
76 76
77 77
78 78 Output format control
79 79
80 80 MM_NOSTD
81 81 Do not use the standard message format, interpret format as
82 82 printf() format. Only catalog access control flags should
83 83 be specified if MM_NOSTD is used; all other flags will be
84 84 ignored.
85 85
86 86
87 87 MM_STD
88 88 Output using the standard message format (default value 0).
89 89
90 90
91 91
92 92 Catalog access control
93 93
94 94 MM_NOGET
95 95 Do not retrieve a localized version of format. In this
96 96 case, only the defmsg field of the format is specified.
97 97
98 98
99 99 MM_GET
100 100 Retrieve a localized version of format from the catalog,
101 101 using msgid as the index and defmsg as the default message
102 102 (default value 0).
103 103
104 104
105 105
106 106 Severity (standard message format only)
107 107
108 108 MM_HALT
109 109 Generate a localized version of HALT, but do not halt the
110 110 machine.
111 111
112 112
113 113 MM_ERROR
114 114 Generate a localized version of ERROR (default value 0).
115 115
116 116
117 117 MM_WARNING
118 118 Generate a localized version of WARNING.
119 119
120 120
121 121 MM_INFO
122 122 Generate a localized version of INFO.
123 123
124 124
125 125
126 126 Additional severities can be defined. Add-on severities can be defined
127 127 with number-string pairs with numeric values from the range [5-255],
128 128 using addsev(3C). The specified severity will be generated from the
129 129 bitwise OR operation of the numeric value and other flags If the
130 130 severity is not defined, pfmt() uses the string SEV=N, where N is
131 131 replaced by the integer severity value passed in flags.
132 132
133 133
134 134 Multiple severities passed in flags will not be detected as an error.
135 135 Any combination of severities will be summed and the numeric value will
136 136 cause the display of either a severity string (if defined) or the
137 137 string SEV=N (if undefined).
138 138
139 139
140 140 Action
141 141
142 142 MM_ACTION
143 143 Specify an action message. Any severity value is
144 144 superseded and replaced by a localized version of TO FIX.
145 145
146 146
147 147 STANDARD ERROR MESSAGE FORMAT
148 148 The pfmt() function displays error messages in the following format:
149 149
150 150 label: severity: text
151 151
152 152
153 153
154 154 If no label was defined by a call to setlabel(3C), the message is
155 155 displayed in the format:
156 156
|
↓ open down ↓ |
156 lines elided |
↑ open up ↑ |
157 157 severity: text
158 158
159 159
160 160
161 161 If pfmt() is called twice to display an error message and a helpful
162 162 action or recovery message, the output can look like:
163 163
164 164 label: severity: textlabel: TO FIX: text
165 165
166 166
167 -
168 -
169 167 RETURN VALUES
170 168 Upon success, pfmt() returns the number of bytes transmitted. Upon
171 169 failure, it returns a negative value:
172 170
173 171 -1
174 172 Write error to stream.
175 173
176 174
177 175 EXAMPLES
178 176 Example 1 Example of pfmt() function.
179 177
180 178
181 179 Example 1:
182 180
183 181
184 182 setlabel("UX:test");
185 183 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\n",
186 184 strerror(errno));
187 185
188 186 displays the message:
189 187
190 188 UX:test: ERROR: Cannot open file: No such file or directory
191 189
192 190
193 191
194 192 Example 2:
195 193
196 194
197 195 setlabel("UX:test");
198 196 setcat("test");
199 197 pfmt(stderr, MM_ERROR, ":10:Syntax error\n");
200 198 pfmt(stderr, MM_ACTION, "55:Usage ...\n");
201 199
202 200
203 201
204 202 displays the message
205 203
206 204
207 205 UX:test: ERROR: Syntax error
208 206 UX:test: TO FIX: Usage ...
209 207
210 208
211 209 USAGE
212 210 Since it uses gettxt(3C), pfmt() should not be used.
213 211
214 212 ATTRIBUTES
215 213 See attributes(5) for descriptions of the following attributes:
216 214
217 215
218 216
219 217
220 218 +---------------+-----------------+
221 219 |ATTRIBUTE TYPE | ATTRIBUTE VALUE |
222 220 +---------------+-----------------+
223 221 |MT-Level | MT-safe |
224 222 +---------------+-----------------+
225 223
226 224 SEE ALSO
227 225 addsev(3C), gettxt(3C), lfmt(3C), printf(3C), setcat(3C), setlabel(3C),
228 226 setlocale(3C), attributes(5), environ(5)
229 227
230 228
231 229
232 230 December 29, 1996 PFMT(3C)
|
↓ open down ↓ |
54 lines elided |
↑ open up ↑ |
XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX