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