fmtmsg(3)

1fmtmsg(3)                  Library Functions Manual                  fmtmsg(3)
2
3
4

NAME

6       fmtmsg - print formatted error messages
7

LIBRARY

9       Standard C library (libc, -lc)
10

SYNOPSIS

12       #include <fmtmsg.h>
13
14       int fmtmsg(long classification, const char *label,
15                  int severity, const char *text,
16                  const char *action, const char *tag);
17

DESCRIPTION

19       This  function displays a message described by its arguments on the de‐
20       vice(s) specified in the classification argument.  For messages written
21       to stderr, the format depends on the MSGVERB environment variable.
22
23       The  label  argument  identifies the source of the message.  The string
24       must consist of two colon separated parts where the first part has  not
25       more than 10 and the second part not more than 14 characters.
26
27       The text argument describes the condition of the error.
28
29       The action argument describes possible steps to recover from the error.
30       If it is printed, it is prefixed by "TO FIX: ".
31
32       The tag argument is a reference to the online documentation where  more
33       information  can  be  found.   It  should contain the label value and a
34       unique identification number.
35
36   Dummy arguments
37       Each of the arguments can have a dummy value.  The dummy classification
38       value  MM_NULLMC  [22m(0L)  does  not  specify  any  output,  so nothing is
39       printed.  The dummy severity value NO_SEV (0) says that no severity  is
40       supplied.   The  values  MM_NULLLBL, MM_NULLTXT, MM_NULLACT, MM_NULLTAG
41       are synonyms for ((char *) 0), the empty string, and  MM_NULLSEV  is  a
42       synonym for NO_SEV.
43
44   The classification argument
45       The  classification argument is the sum of values describing 4 types of
46       information.
47
48       The first value defines the output channel.
49
50       MM_PRINT    Output to stderr.
51
52       MM_CONSOLE  Output to the system console.
53
54       MM_PRINT | MM_CONSOLE
55                   Output to both.
56
57       The second value is the source of the error:
58
59       MM_HARD     A hardware error occurred.
60
61       MM_FIRM     A firmware error occurred.
62
63       MM_SOFT     A software error occurred.
64
65       The third value encodes the detector of the problem:
66
67       MM_APPL     It is detected by an application.
68
69       MM_UTIL     It is detected by a utility.
70
71       MM_OPSYS    It is detected by the operating system.
72
73       The fourth value shows the severity of the incident:
74
75       MM_RECOVER  It is a recoverable error.
76
77       MM_NRECOV   It is a nonrecoverable error.
78
79   The severity argument
80       The severity argument can take one of the following values:
81
82       MM_NOSEV    No severity is printed.
83
84       MM_HALT     This value is printed as HALT.
85
86       MM_ERROR    This value is printed as ERROR.
87
88       MM_WARNING  This value is printed as WARNING.
89
90       MM_INFO     This value is printed as INFO.
91
92       The numeric values are between 0 and 4.  Using  addseverity(3)  or  the
93       environment  variable  SEV_LEVEL you can add more levels and strings to
94       print.
95

RETURN VALUE

97       The function can return 4 values:
98
99       MM_OK       Everything went smooth.
100
101       MM_NOTOK    Complete failure.
102
103       MM_NOMSG    Error writing to stderr.
104
105       MM_NOCON    Error writing to the console.
106

ENVIRONMENT

108       The environment variable MSGVERB ("message verbosity") can be  used  to
109       suppress  parts of the output to stderr.  (It does not influence output
110       to the console.)  When this variable is defined, is non-NULL, and is  a
111       colon-separated list of valid keywords, then only the parts of the mes‐
112       sage corresponding to these keywords is printed.   Valid  keywords  are
113       "label", "severity", "text", "action", and "tag".
114
115       The  environment variable SEV_LEVEL can be used to introduce new sever‐
116       ity levels.  By default, only the five severity levels described  above
117       are available.  Any other numeric value would make fmtmsg() print noth‐
118       ing.  If the user puts SEV_LEVEL with a format like
119
120              SEV_LEVEL=[description[:description[:...]]]
121
122       in the environment of the process before the first  call  to  fmtmsg(),
123       where each description is of the form
124
125              severity-keyword,level,printstring
126
127       then  fmtmsg()  will also accept the indicated values for the level (in
128       addition to the standard levels 0–4), and use the indicated printstring
129       when such a level occurs.
130
131       The  severity-keyword  part  is  not  used by fmtmsg() but it has to be
132       present.  The level part is a string representation of a  number.   The
133       numeric value must be a number greater than 4.  This value must be used
134       in the severity argument of fmtmsg() to select this class.  It  is  not
135       possible  to  overwrite any of the predefined classes.  The printstring
136       is the string printed when a message of  this  class  is  processed  by
137       fmtmsg().
138

ATTRIBUTES

140       For  an  explanation  of  the  terms  used  in  this  section,  see at‐
141       tributes(7).
142
143       ┌──────────┬───────────────┬───────────────────────────────────────────┐
144       │Interface │ Attribute     │ Value                                     │
145       ├──────────┼───────────────┼───────────────────────────────────────────┤
146       │fmtmsg()  │ Thread safety │ glibc >= 2.16: MT-Safe; glibc < 2.16: MT- │
147       │          │               │ Unsafe                                    │
148       └──────────┴───────────────┴───────────────────────────────────────────┘
149
150       Before glibc 2.16, the fmtmsg() function uses a static variable that is
151       not protected, so it is not thread-safe.
152
153       Since glibc 2.16, the fmtmsg() function uses  a  lock  to  protect  the
154       static variable, so it is thread-safe.
155

STANDARDS

157       fmtmsg()
158       MSGVERB
159              POSIX.1-2008.
160

HISTORY

162       fmtmsg()
163              System V.  POSIX.1-2001 and POSIX.1-2008.  glibc 2.1.
164
165       MSGVERB
166              System V.  POSIX.1-2001 and POSIX.1-2008.
167
168       SEV_LEVEL
169              System V.
170
171       System  V and UnixWare man pages tell us that these functions have been
172       replaced by "pfmt() and addsev()" or by "pfmt(), vpfmt(),  lfmt(),  and
173       vlfmt()", and will be removed later.
174

EXAMPLES

176       #include <fmtmsg.h>
177       #include <stdio.h>
178       #include <stdlib.h>
179
180       int
181       main(void)
182       {
183           long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
184           int err;
185
186           err = fmtmsg(class, "util-linux:mount", MM_ERROR,
187                        "unknown mount option", "See mount(8).",
188                        "util-linux:mount:017");
189           switch (err) {
190           case MM_OK:
191               break;
192           case MM_NOTOK:
193               printf("Nothing printed\n");
194               break;
195           case MM_NOMSG:
196               printf("Nothing printed to stderr\n");
197               break;
198           case MM_NOCON:
199               printf("No console output\n");
200               break;
201           default:
202               printf("Unknown error from fmtmsg()\n");
203           }
204           exit(EXIT_SUCCESS);
205       }
206
207       The output should be:
208
209           util-linux:mount: ERROR: unknown mount option
210           TO FIX: See mount(8).  util-linux:mount:017
211
212       and after
213
214           MSGVERB=text:action; export MSGVERB
215
216       the output becomes:
217
218           unknown mount option
219           TO FIX: See mount(8).
220