1pfmt(3C)                 Standard C Library Functions                 pfmt(3C)
2
3
4

NAME

6       pfmt - display error message in standard format
7

SYNOPSIS

9       #include <pfmt.h>
10
11       int pfmt(FILE *stream, long flags, char *format, ... /* arg */);
12
13

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 mes‐
21       sage format (unless MM_NOSTD is specified, in which case the output  is
22       similar to printf()).
23
24
25       If  the  printf() format string is to be retrieved from a message data‐
26       base, 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  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
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 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
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 mes‐
70       sage  format),  and the access to message catalogs to retrieve a local‐
71       ized version of format.
72
73
74       The flags argument is composed of several groups, and can take the fol‐
75       lowing values (one from each group):
76
77
78       Output format control
79
80       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
85
86       MM_STD      Output using the standard message format (default value 0).
87
88
89
90       Catalog access control
91
92       MM_NOGET    Do not retrieve a localized  version  of  format.  In  this
93                   case, only the defmsg field of the format is specified.
94
95
96       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
100
101
102       Severity (standard message format only)
103
104       MM_HALT       Generate a localized version of HALT, but do not halt the
105                     machine.
106
107
108       MM_ERROR      Generate a localized version of ERROR (default value 0).
109
110
111       MM_WARNING    Generate a localized version of WARNING.
112
113
114       MM_INFO       Generate a localized version of INFO.
115
116
117
118       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
125
126       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
131
132       Action
133
134       MM_ACTION    Specify an action message. Any severity  value  is  super‐
135                    seded and replaced by a localized version of TO FIX.
136
137

STANDARD ERROR MESSAGE FORMAT

139       The pfmt() function displays error messages in the following format:
140
141         label: severity: text
142
143
144
145       If  no label was defined by a call to setlabel(3C), the message is dis‐
146       played in the format:
147
148         severity: text
149
150
151
152       If pfmt() is called twice to display an error  message  and  a  helpful
153       action or recovery message, the output can look like:
154
155         label: severity: textlabel: TO FIX: text
156
157
158
159

RETURN VALUES

161       Upon  success,  pfmt()  returns  the  number of bytes transmitted. Upon
162       failure, it returns a negative value:
163
164       −1       Write error to stream.
165
166

EXAMPLES

168       Example 1 Example of pfmt() function.
169
170
171       Example 1:
172
173
174         setlabel("UX:test");
175         pfmt(stderr, MM_ERROR, "test:2:Cannot open file: %s\n",
176              strerror(errno));
177
178         displays the message:
179
180         UX:test: ERROR: Cannot open file: No such file or directory
181
182
183
184       Example 2:
185
186
187         setlabel("UX:test");
188         setcat("test");
189         pfmt(stderr, MM_ERROR, ":10:Syntax error\n");
190         pfmt(stderr, MM_ACTION, "55:Usage ...\n");
191
192
193
194       displays the message
195
196
197         UX:test: ERROR: Syntax error
198         UX:test: TO FIX: Usage ...
199
200

USAGE

202       Since it uses gettxt(3C), pfmt() should not be used.
203

ATTRIBUTES

205       See attributes(5) for descriptions of the following attributes:
206
207
208
209
210       ┌─────────────────────────────┬─────────────────────────────┐
211       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
212       ├─────────────────────────────┼─────────────────────────────┤
213       │MT-Level                     │MT-safe                      │
214       └─────────────────────────────┴─────────────────────────────┘
215

SEE ALSO

217       addsev(3C), gettxt(3C), lfmt(3C), printf(3C), setcat(3C), setlabel(3C),
218       setlocale(3C), attributes(5), environ(5)
219
220
221
222SunOS 5.11                        29 Dec 1996                         pfmt(3C)
Impressum