man3/fmtmsg.3

   1 .\"  Copyright 2002 walter harms (walter.harms@informatik.uni-oldenburg.de)
   2 .\"
   3 .\" SPDX-License-Identifier: GPL-1.0-or-later
   4 .\"
   5 .\"  adapted glibc info page
   6 .\"
   7 .\"  This should run as 'Guru Meditation' (amiga joke :)
   8 .\"  The function is quite complex and deserves an example
   9 .\"
  10 .\"  Polished, aeb, 2003-11-01
  11 .TH FMTMSG 3 2021-03-22 "Linux man-pages (unreleased)" "Linux Programmer's Manual"
  12 .SH NAME
  13 fmtmsg \- print formatted error messages
  14 .SH LIBRARY
  15 Standard C library
  16 .RI ( libc ", " \-lc )
  17 .SH SYNOPSIS
  18 .nf
  19 .B #include <fmtmsg.h>
  20 .PP
  21 .BI "int fmtmsg(long " classification ", const char *" label ,
  22 .BI "           int " severity ", const char *" text ,
  23 .BI "           const char *" action ", const char *" tag );
  24 .fi
  25 .SH DESCRIPTION
  26 This function displays a message described by its arguments on the device(s)
  27 specified in the
  28 .I classification
  29 argument.
  30 For messages written to
  31 .IR stderr ,
  32 the format depends on the
  33 .B MSGVERB
  34 environment variable.
  35 .PP
  36 The
  37 .I label
  38 argument identifies the source of the message.
  39 The string must consist
  40 of two colon separated parts where the first part has not more
  41 than 10 and the second part not more than 14 characters.
  42 .PP
  43 The
  44 .I text
  45 argument describes the condition of the error.
  46 .PP
  47 The
  48 .I action
  49 argument describes possible steps to recover from the error.
  50 If it is printed, it is prefixed by "TO FIX: ".
  51 .PP
  52 The
  53 .I tag
  54 argument is a reference to the online documentation where more
  55 information can be found.
  56 It should contain the
  57 .I label
  58 value and a unique identification number.
  59 .SS Dummy arguments
  60 Each of the arguments can have a dummy value.
  61 The dummy classification value
  62 .B MM_NULLMC
  63 (0L) does not specify any output, so nothing is printed.
  64 The dummy severity value
  65 .B NO_SEV
  66 (0) says that no severity is supplied.
  67 The values
  68 .BR MM_NULLLBL ,
  69 .BR MM_NULLTXT ,
  70 .BR MM_NULLACT ,
  71 .B MM_NULLTAG
  72 are synonyms for
  73 .IR "((char\ *)\ 0)" ,
  74 the empty string, and
  75 .B MM_NULLSEV
  76 is a synonym for
  77 .BR NO_SEV .
  78 .SS The classification argument
  79 The
  80 .I classification
  81 argument is the sum of values describing 4 types of information.
  82 .PP
  83 The first value defines the output channel.
  84 .TP 12n
  85 .B MM_PRINT
  86 Output to
  87 .IR stderr .
  88 .TP
  89 .B MM_CONSOLE
  90 Output to the system console.
  91 .TP
  92 .B "MM_PRINT | MM_CONSOLE"
  93 Output to both.
  94 .PP
  95 The second value is the source of the error:
  96 .TP 12n
  97 .B MM_HARD
  98 A hardware error occurred.
  99 .TP
 100 .B MM_FIRM
 101 A firmware error occurred.
 102 .TP
 103 .B MM_SOFT
 104 A software error occurred.
 105 .PP
 106 The third value encodes the detector of the problem:
 107 .TP 12n
 108 .B MM_APPL
 109 It is detected by an application.
 110 .TP
 111 .B MM_UTIL
 112 It is detected by a utility.
 113 .TP
 114 .B MM_OPSYS
 115 It is detected by the operating system.
 116 .PP
 117 The fourth value shows the severity of the incident:
 118 .TP 12n
 119 .B MM_RECOVER
 120 It is a recoverable error.
 121 .TP
 122 .B MM_NRECOV
 123 It is a nonrecoverable error.
 124 .SS The severity argument
 125 The
 126 .I severity
 127 argument can take one of the following values:
 128 .TP 12n
 129 .B MM_NOSEV
 130 No severity is printed.
 131 .TP
 132 .B MM_HALT
 133 This value is printed as HALT.
 134 .TP
 135 .B MM_ERROR
 136 This value is printed as ERROR.
 137 .TP
 138 .B MM_WARNING
 139 This value is printed as WARNING.
 140 .TP
 141 .B MM_INFO
 142 This value is printed as INFO.
 143 .PP
 144 The numeric values are between 0 and 4.
 145 Using
 146 .BR addseverity (3)
 147 or the environment variable
 148 .B SEV_LEVEL
 149 you can add more levels and strings to print.
 150 .SH RETURN VALUE
 151 The function can return 4 values:
 152 .TP 12n
 153 .B MM_OK
 154 Everything went smooth.
 155 .TP
 156 .B MM_NOTOK
 157 Complete failure.
 158 .TP
 159 .B MM_NOMSG
 160 Error writing to
 161 .IR stderr .
 162 .TP
 163 .B MM_NOCON
 164 Error writing to the console.
 165 .SH ENVIRONMENT
 166 The environment variable
 167 .B MSGVERB
 168 ("message verbosity") can be used to suppress parts of
 169 the output to
 170 .IR stderr .
 171 (It does not influence output to the console.)
 172 When this variable is defined, is non-NULL, and is a colon-separated
 173 list of valid keywords, then only the parts of the message corresponding
 174 to these keywords is printed.
 175 Valid keywords are "label", "severity", "text", "action", and "tag".
 176 .PP
 177 The environment variable
 178 .B SEV_LEVEL
 179 can be used to introduce new severity levels.
 180 By default, only the five severity levels described
 181 above are available.
 182 Any other numeric value would make
 183 .BR fmtmsg ()
 184 print nothing.
 185 If the user puts
 186 .B SEV_LEVEL
 187 with a format like
 188 .PP
 189 .RS
 190 SEV_LEVEL=[description[:description[:...]]]
 191 .RE
 192 .PP
 193 in the environment of the process before the first call to
 194 .BR fmtmsg (),
 195 where each description is of the form
 196 .PP
 197 .RS
 198 severity-keyword,level,printstring
 199 .RE
 200 .PP
 201 then
 202 .BR fmtmsg ()
 203 will also accept the indicated values for the level (in addition to
 204 the standard levels 0\(en4), and use the indicated printstring when
 205 such a level occurs.
 206 .PP
 207 The severity-keyword part is not used by
 208 .BR fmtmsg ()
 209 but it has to be present.
 210 The level part is a string representation of a number.
 211 The numeric value must be a number greater than 4.
 212 This value must be used in the severity argument of
 213 .BR fmtmsg ()
 214 to select this class.
 215 It is not possible to overwrite
 216 any of the predefined classes.
 217 The printstring
 218 is the string printed when a message of this class is processed by
 219 .BR fmtmsg ().
 220 .SH VERSIONS
 221 .BR fmtmsg ()
 222 is provided in glibc since version 2.1.
 223 .SH ATTRIBUTES
 224 For an explanation of the terms used in this section, see
 225 .BR attributes (7).
 226 .ad l
 227 .nh
 228 .TS
 229 allbox;
 230 lb lb lbx
 231 l l l.
 232 Interface       Attribute       Value
 233 T{
 234 .BR fmtmsg ()
 235 T}      Thread safety   T{
 236 glibc\ >=\ 2.16: MT-Safe;
 237 glibc\ <\ 2.16: MT-Unsafe
 238 T}
 239 .TE
 240 .hy
 241 .ad
 242 .sp 1
 243 .PP
 244 Before glibc 2.16, the
 245 .BR fmtmsg ()
 246 function uses a static variable that is not protected,
 247 so it is not thread-safe.
 248 .PP
 249 Since glibc 2.16,
 250 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
 251 the
 252 .BR fmtmsg ()
 253 function uses a lock to protect the static variable, so it is thread-safe.
 254 .SH STANDARDS
 255 The functions
 256 .BR fmtmsg ()
 257 and
 258 .BR addseverity (3),
 259 and environment variables
 260 .B MSGVERB
 261 and
 262 .B SEV_LEVEL
 263 come from System V.
 264 .PP
 265 The function
 266 .BR fmtmsg ()
 267 and the environment variable
 268 .B MSGVERB
 269 are described in POSIX.1-2001 and POSIX.1-2008.
 270 .SH NOTES
 271 System V and UnixWare man pages tell us that these functions
 272 have been replaced by "pfmt() and addsev()" or by "pfmt(),
 273 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 274 .SH EXAMPLES
 275 .EX
 276 #include <stdio.h>
 277 #include <stdlib.h>
 278 #include <fmtmsg.h>
 279
 280 int
 281 main(void)
 282 {
 283     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 284     int err;
 285
 286     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 287                 "unknown mount option", "See mount(8).",
 288                 "util\-linux:mount:017");
 289     switch (err) {
 290     case MM_OK:
 291         break;
 292     case MM_NOTOK:
 293         printf("Nothing printed\en");
 294         break;
 295     case MM_NOMSG:
 296         printf("Nothing printed to stderr\en");
 297         break;
 298     case MM_NOCON:
 299         printf("No console output\en");
 300         break;
 301     default:
 302         printf("Unknown error from fmtmsg()\en");
 303     }
 304     exit(EXIT_SUCCESS);
 305 }
 306 .EE
 307 .PP
 308 The output should be:
 309 .PP
 310 .in +4n
 311 .EX
 312 util\-linux:mount: ERROR: unknown mount option
 313 TO FIX: See mount(8).  util\-linux:mount:017
 314 .EE
 315 .in
 316 .PP
 317 and after
 318 .PP
 319 .in +4n
 320 .EX
 321 MSGVERB=text:action; export MSGVERB
 322 .EE
 323 .in
 324 .PP
 325 the output becomes:
 326 .PP
 327 .in +4n
 328 .EX
 329 unknown mount option
 330 TO FIX: See mount(8).
 331 .EE
 332 .in
 333 .SH SEE ALSO
 334 .BR addseverity (3),
 335 .BR perror (3)