original/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 2013-06-21 "" "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 .SS Multithreading (see pthreads(7))
 227 Before glibc 2.16, the
 228 .BR fmtmsg ()
 229 function uses a static variable that is not protected,
 230 so it is not thread-safe.
 231
 232 Since glibc 2.16,
 233 .\" Modified in commit 7724defcf8873116fe4efab256596861eef21a94
 234 the
 235 .BR fmtmsg ()
 236 function uses a lock to protect the static variable, so it is thread-safe.
 237 .SH CONFORMING TO
 238 The functions
 239 .BR fmtmsg ()
 240 and
 241 .BR addseverity (3),
 242 and environment variables
 243 .B MSGVERB
 244 and
 245 .B SEV_LEVEL
 246 come from System V.
 247 The function
 248 .BR fmtmsg ()
 249 and the environment variable
 250 .B MSGVERB
 251 are described in POSIX.1-2001.
 252 .SH NOTES
 253 System V and UnixWare man pages tell us that these functions
 254 have been replaced by "pfmt() and addsev()" or by "pfmt(),
 255 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 256 .SH EXAMPLE
 257 .nf
 258 #include <stdio.h>
 259 #include <stdlib.h>
 260 #include <fmtmsg.h>
 261
 262 int
 263 main(void)
 264 {
 265     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 266     int err;
 267
 268     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 269                 "unknown mount option", "See mount(8).",
 270                 "util\-linux:mount:017");
 271     switch (err) {
 272     case MM_OK:
 273         break;
 274     case MM_NOTOK:
 275         printf("Nothing printed\en");
 276         break;
 277     case MM_NOMSG:
 278         printf("Nothing printed to stderr\en");
 279         break;
 280     case MM_NOCON:
 281         printf("No console output\en");
 282         break;
 283     default:
 284         printf("Unknown error from fmtmsg()\en");
 285     }
 286     exit(EXIT_SUCCESS);
 287 }
 288 .fi
 289 .PP
 290 The output should be:
 291 .nf
 292
 293     util\-linux:mount: ERROR: unknown mount option
 294     TO FIX: See mount(8).  util\-linux:mount:017
 295
 296 .fi
 297 and after
 298 .nf
 299
 300     MSGVERB=text:action; export MSGVERB
 301
 302 .fi
 303 the output becomes:
 304 .nf
 305
 306     unknown mount option
 307     TO FIX: See mount(8).
 308 .fi
 309 .SH SEE ALSO
 310 .BR addseverity (3),
 311 .BR perror (3)
 312 .SH COLOPHON
 313 This page is part of release 3.79 of the Linux
 314 .I man-pages
 315 project.
 316 A description of the project,
 317 information about reporting bugs,
 318 and the latest version of this page,
 319 can be found at
 320 \%http://www.kernel.org/doc/man\-pages/.