original/man3/fmtmsg.3

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