man3/fmtmsg.3

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