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

NAME

6       lfmt - display error message in standard format and pass to logging and
7       monitoring services
8

SYNOPSIS

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

DESCRIPTION

16       The lfmt() function retrieves a format string  from  a  locale-specific
17       message  database  (unless   MM_NOGET  is  specified)  and  uses it for
18       printf(3C) style formatting of args. The output is displayed on stream.
19       If stream is  NULL no output is displayed.
20
21
22       The  lfmt() function encapsulates the output in the standard error mes‐
23       sage format (unless  MM_NOSTD is specified, in which case the output is
24       like  that of printf(). It forwards its output to the logging and moni‐
25       toring facility, even if stream is  NULL. Optionally,  lfmt()  displays
26       the output on the console with a date and time stamp.
27
28
29       If  the  printf() format string is to be retrieved from a message data‐
30       base, the format argument must have the following structure:
31
32
33       <catalog>:<msgnum>:<defmsg>.
34
35
36       If  MM_NOGET is specified,  only the <defmsg> field must be specified.
37
38
39       The <catalog> field indicates the message database  that  contains  the
40       localized  version  of  the  format string. This field is limited to 14
41       characters selected from a set of all characters values, excluding  the
42       null character (\0) and the ASCII codes for slash (/) and colon (:).
43
44
45       The <msgnum> field is a positive number that indicates the index of the
46       string into the message database.
47
48
49       If the catalog does not exist in the locale (specified by the last call
50       to  setlocale(3C)  using the  LC_ALL or  LC_MESSAGES categories), or if
51       the message number is out of bound, lfmt() will attempt to retrieve the
52       message  from the C locale. If this second retrieval fails, lfmt() uses
53       the <defmsg> field of the format argument.
54
55
56       If <catalog> is omitted, lfmt() will attempt  to  retrieve  the  string
57       from  the  default catalog specified by the last call to setcat(3C). In
58       this case, the format argument has the following structure:
59
60
61       :<msgnum>:<defmsg>.
62
63
64       The lfmt() function will output the message
65
66
67       Message not found!!\n
68
69
70       as the format string if <catalog> is not a valid catalog  name,  if  no
71       catalog  is specified (either explicitly or with setcat()), if <msgnum>
72       is not a valid number, or if no message could  be  retrieved  from  the
73       message databases and <defmsg> was omitted.
74
75
76       The  flags  argument  determines the type of output (whether the format
77       should be interpreted as it is or be encapsulated in the standard  mes‐
78       sage format) and the access to message catalogs to retrieve a localized
79       version of format.
80
81
82       The flags argument is composed of several groups, and can take the fol‐
83       lowing values (one from each group):
84
85       Output format control
86
87
88           MM_NOSTD    Do  not  use  the standard message format but interpret
89                       format as a printf() format. Only catalog  access  con‐
90                       trol  flags, console display control and logging infor‐
91                       mation should be specified if  MM_NOSTD  is  used;  all
92                       other flags will be ignored.
93
94
95           MM_STD      Output using the standard message format (default value
96                       is 0).
97
98
99
100       Catalog access control
101
102
103           MM_NOGET    Do not retrieve a localized version of format. In  this
104                       case, only the <defmsg> field of format is specified.
105
106
107           MM_GET      Retrieve  a localized version of format from <catalog>,
108                       using <msgid> as the index and <defmsg> as the  default
109                       message (default value is 0).
110
111
112
113       Severity (standard message format only)
114
115
116           MM_HALT       Generate a localized version of  HALT, but donot halt
117                         the machine.
118
119
120           MM_ERROR      Generate a localized version of  ERROR (default value
121                         is 0).
122
123
124           MM_WARNING    Generate a localized version of  WARNING.
125
126
127           MM_INFO       Generate a localized version of  INFO.
128
129           Additional  severities can be defined with the addsev(3C) function,
130           using number-string pairs with numeric values in the range [5-255].
131           The specified severity is formed by the bitwise OR operation of the
132           numeric value and other flags arguments.
133
134           If the severity is not defined, lfmt() uses the string  SEV=N where
135           N is the integer severity value passed in flags.
136
137           Multiple  severities  passed  in  flags  will not be detected as an
138           error. Any combination of severities will be summed and the numeric
139           value  will  cause  the  display  of  either  a severity string (if
140           defined) or the string SEV=N (if undefined).
141
142
143       Action
144
145
146           MM_ACTION    Specify an  action  message.  Any  severity  value  is
147                        superseded  and  replaced by a localized version of TO
148                        FIX.
149
150
151
152       Console display control
153
154
155           MM_CONSOLE      Display the message to the console in  addition  to
156                           the specified stream.
157
158
159           MM_NOCONSOLE    Do  not display the message to the console in addi‐
160                           tion to the specified stream (default value is 0).
161
162
163
164       Logging information
165
166
167           Major classification
168
169               Identify the source of the condition. Identifiers are:  MM_HARD
170               (hardware), MM_SOFT (software), and MM_FIRM (firmware).
171
172
173           Message source subclassification
174
175               Identify  the type of software in which the problem is spotted.
176               Identifiers are: MM_APPL (application), MM_UTIL (utility),  and
177               MM_OPSYS (operating system).
178
179
180

STANDARD ERROR MESSAGE FORMAT

182       The lfmt() function displays error messages in the following format:
183
184         label: severity: text
185
186
187
188       If  no label was defined by a call to setlabel(3C), the message is dis‐
189       played in the format:
190
191         severity: text
192
193
194
195       If lfmt() is called twice to display an error  message  and  a  helpful
196       action or recovery message, the output may appear as follows:
197
198         label: severity: text
199         label:  TO FIX: text
200
201

RETURN VALUES

203       Upon  successful  completion, lfmt() returns the number of bytes trans‐
204       mitted.  Otherwise, it returns a negative value:
205
206       −1       Write the error to stream.
207
208
209       −2       Cannot log and/or display at console.
210
211

USAGE

213       Since lfmt() uses gettxt(3C), it is  recommended  that  lfmt()  not  be
214       used.
215

EXAMPLES

217       Example 1 The following example
218
219         setlabel("UX:test");
220         lfmt(stderr, MM_ERROR|MM_CONSOLE|MM_SOFT|MM_UTIL,
221              "test:2:Cannot open file: %s\n", strerror(errno));
222
223
224
225       displays  the  message to stderr and to the console and makes it avail‐
226       able for logging:
227
228
229         UX:test: ERROR: Cannot open file: No such file or directory
230
231
232       Example 2 The following example
233
234         setlabel("UX:test");
235         lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
236                 "test:23:test facility is enabled\n");
237
238
239
240       displays the message to stderr and makes it available for logging:
241
242
243         UX:test: INFO: test facility enabled
244
245

ATTRIBUTES

247       See attributes(5) for descriptions of the following attributes:
248
249
250
251
252       ┌─────────────────────────────┬─────────────────────────────┐
253       │      ATTRIBUTE TYPE         │      ATTRIBUTE VALUE        │
254       ├─────────────────────────────┼─────────────────────────────┤
255       │MT-Level                     │MT-Safe                      │
256       └─────────────────────────────┴─────────────────────────────┘
257

SEE ALSO

259       addsev(3C), gettxt(3C), pfmt(3C), printf(3C), setcat(3C), setlabel(3C),
260       setlocale(3C), attributes(5), environ(5)
261
262
263
264SunOS 5.11                        29 Dec 1996                         lfmt(3C)
Impressum