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 2017-09-15 "" "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 .TS
 226 allbox;
 227 lb lb lbw23
 228 l l l.
 229 Interface       Attribute       Value
 230 T{
 231 .BR fmtmsg ()
 232 T}      Thread safety   T{
 233 glibc >= 2.16: MT-Safe
 234 .br
 235 glibc < 2.16: MT-Unsafe
 236 T}
 237 .TE
 238 .PP
 239 Before glibc 2.16, the
 240 .BR fmtmsg ()
 241 function uses a static variable that is not protected,
 242 so it is not thread-safe.
 243 .PP
 244 Since glibc 2.16,
 245 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
 246 the
 247 .BR fmtmsg ()
 248 function uses a lock to protect the static variable, so it is thread-safe.
 249 .SH CONFORMING TO
 250 The functions
 251 .BR fmtmsg ()
 252 and
 253 .BR addseverity (3),
 254 and environment variables
 255 .B MSGVERB
 256 and
 257 .B SEV_LEVEL
 258 come from System V.
 259 .PP
 260 The function
 261 .BR fmtmsg ()
 262 and the environment variable
 263 .B MSGVERB
 264 are described in POSIX.1-2001 and POSIX.1-2008.
 265 .SH NOTES
 266 System V and UnixWare man pages tell us that these functions
 267 have been replaced by "pfmt() and addsev()" or by "pfmt(),
 268 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 269 .SH EXAMPLE
 270 .EX
 271 #include <stdio.h>
 272 #include <stdlib.h>
 273 #include <fmtmsg.h>
 274
 275 int
 276 main(void)
 277 {
 278     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 279     int err;
 280
 281     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 282                 "unknown mount option", "See mount(8).",
 283                 "util\-linux:mount:017");
 284     switch (err) {
 285     case MM_OK:
 286         break;
 287     case MM_NOTOK:
 288         printf("Nothing printed\en");
 289         break;
 290     case MM_NOMSG:
 291         printf("Nothing printed to stderr\en");
 292         break;
 293     case MM_NOCON:
 294         printf("No console output\en");
 295         break;
 296     default:
 297         printf("Unknown error from fmtmsg()\en");
 298     }
 299     exit(EXIT_SUCCESS);
 300 }
 301 .EE
 302 .PP
 303 The output should be:
 304 .PP
 305 .in +4n
 306 .EX
 307 util\-linux:mount: ERROR: unknown mount option
 308 TO FIX: See mount(8).  util\-linux:mount:017
 309 .EE
 310 .in
 311 .PP
 312 and after
 313 .PP
 314 .in +4n
 315 .EX
 316 MSGVERB=text:action; export MSGVERB
 317 .EE
 318 .in
 319 .PP
 320 the output becomes:
 321 .PP
 322 .in +4n
 323 .EX
 324 unknown mount option
 325 TO FIX: See mount(8).
 326 .EE
 327 .in
 328 .PP
 329 .SH SEE ALSO
 330 .BR addseverity (3),
 331 .BR perror (3)