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