1pfmt(3C) Standard C Library Functions pfmt(3C)
2
6 pfmt - display error message in standard format
7
9 #include <pfmt.h>
10 int pfmt(FILE *stream, long flags, char *format, ... /* arg */);
12
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 The pfmt() function encapsulates the output in the standard error mes‐
21 sage format (unless MM_NOSTD is specified, in which case the output is
22 similar to printf()).
23 If the printf() format string is to be retrieved from a message data‐
26 base, the format argument must have the following structure:
27 <catalog>:<msgnum>:<defmsg>.
30 If MM_NOGET is specified, only the defmsg field must be specified.
33 The catalog field is used to indicate the message database that con‐
36 tains the localized version of the format string. This field must be
37 limited to 14 characters selected from the set of all characters val‐
38 ues, excluding \0 (null) and the ASCII codes for / (slash) and :
39 (colon).
40 The msgnum field is a positive number that indicates the index of the
43 string into the message database.
44 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 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 :<msgnum>:<defmsg>.
59 The pfmt() will output Message not found!!\n as format string if cata‐
62 log 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 The flags argument determine the type of output (such as whether the
69 format should be interpreted as is or encapsulated in the standard mes‐
70 sage format), and the access to message catalogs to retrieve a local‐
71 ized version of format.
72 The flags argument is composed of several groups, and can take the fol‐
75 lowing values (one from each group):
76 Output format control
79 MM_NOSTD Do not use the standard message format, interpret format as
81 printf() format. Only catalog access control flags should
82 be specified if MM_NOSTD is used; all other flags will be
83 ignored.
84 MM_STD Output using the standard message format (default value 0).
87 Catalog access control
91 MM_NOGET Do not retrieve a localized version of format. In this
93 case, only the defmsg field of the format is specified.
94 MM_GET Retrieve a localized version of format from the catalog,
97 using msgid as the index and defmsg as the default message
98 (default value 0).
99 Severity (standard message format only)
103 MM_HALT Generate a localized version of HALT, but do not halt the
105 machine.
106 MM_ERROR Generate a localized version of ERROR (default value 0).
109 MM_WARNING Generate a localized version of WARNING.
112 MM_INFO Generate a localized version of INFO.
115 Additional severities can be defined. Add-on severities can be defined
119 with number-string pairs with numeric values from the range [5-255],
120 using addsev(3C). The specified severity will be generated from the
121 bitwise OR operation of the numeric value and other flags If the sever‐
122 ity is not defined, pfmt() uses the string SEV=N, where N is replaced
123 by the integer severity value passed in flags.
124 Multiple severities passed in flags will not be detected as an error.
127 Any combination of severities will be summed and the numeric value will
128 cause the display of either a severity string (if defined) or the
129 string SEV=N (if undefined).
130 Action
133 MM_ACTION Specify an action message. Any severity value is super‐
135 seded and replaced by a localized version of TO FIX.
136
139 The pfmt() function displays error messages in the following format:
140 label: severity: text
142 If no label was defined by a call to setlabel(3C), the message is dis‐
146 played in the format:
147 severity: text
149 If pfmt() is called twice to display an error message and a helpful
153 action or recovery message, the output can look like:
154 label: severity: textlabel: TO FIX: text
156
161 Upon success, pfmt() returns the number of bytes transmitted. Upon
162 failure, it returns a negative value:
163 −1 Write error to stream.
165
168 Example 1 Example of pfmt() function.
169 Example 1:
172 setlabel("UX:test");
175 pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\n",
176 strerror(errno));
177 displays the message:
179 UX:test: ERROR: Cannot open file: No such file or directory
181 Example 2:
185 setlabel("UX:test");
188 setcat("test");
189 pfmt(stderr, MM_ERROR, ":10:Syntax error\n");
190 pfmt(stderr, MM_ACTION, "55:Usage ...\n");
191 displays the message
195 UX:test: ERROR: Syntax error
198 UX:test: TO FIX: Usage ...
199
202 Since it uses gettxt(3C), pfmt() should not be used.
203
205 See attributes(5) for descriptions of the following attributes:
206 ┌─────────────────────────────┬─────────────────────────────┐
211 │ ATTRIBUTE TYPE │ ATTRIBUTE VALUE │
212 ├─────────────────────────────┼─────────────────────────────┤
213 │MT-Level │MT-safe │
214 └─────────────────────────────┴─────────────────────────────┘
215
217 addsev(3C), gettxt(3C), lfmt(3C), printf(3C), setcat(3C), setlabel(3C),
218 setlocale(3C), attributes(5), environ(5)
219SunOS 5.11 29 Dec 1996 pfmt(3C)