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 an deserves an example
   7 .\"
   8 .\"  Polished, aeb, 2003-11-01
   9 .TH fmtmsg 3 2003-11-01 "" "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 parameters on the device(s)
  24 specified in the
  25 .I classification
  26 parameter.
  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 parameter 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 parameter describes the condition of the error.
  43 .LP
  44 The
  45 .I action
  46 parameter 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 parameter 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 parameters"
  57 Each of the parameters 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 .BR MM_NULLTAG
  69 are synonyms for ((char *) 0), the empty string, and
  70 .B MM_NULLSEV
  71 is a synonym for
  72 .BR NO_SEV .
  73 .SS "The classification parameter"
  74 The
  75 .I classification
  76 parameter is the sum of values describing 4 types of information.
  77 .br
  78 .sp
  79 The first value defines the output channel.
  80 .TP 12n
  81 .B MM_PRINT
  82 Output to
  83 .IR stderr .
  84 .TP
  85 .B MM_CONSOLE
  86 Output to the system console.
  87 .TP
  88 .B "MM_PRINT | MM_CONSOLE"
  89 Output to both.
  90 .PP
  91 The second value is the source of the error:
  92 .TP 12n
  93 .B MM_HARD
  94 A hardware error occurred.
  95 .TP
  96 .B MM_FIRM
  97 A firmware error occurred.
  98 .TP
  99 .B MM_SOFT
 100 A software error occurred.
 101 .PP
 102 The third value encodes the detector of the problem:
 103 .TP 12n
 104 .B MM_APPL
 105 It is detected by an application.
 106 .TP
 107 .B MM_UTIL
 108 It is detected by a utility.
 109 .TP
 110 .B MM_OPSYS
 111 It is detected by the operating system.
 112 .PP
 113 The fourth value shows the severity of the incident:
 114 .TP 12n
 115 .B MM_RECOVER
 116 It is a recoverable error.
 117 .TP
 118 .B MM_NRECOV
 119 It is a non-recoverable error.
 120 .SS "The severity parameter"
 121 The
 122 .I severity
 123 parameter can take one of the following values:
 124 .TP 12n
 125 .B MM_NOSEV
 126 No severity is printed.
 127 .TP
 128 .B MM_HALT
 129 This value is printed as HALT.
 130 .TP
 131 .B MM_ERROR
 132 This value is printed as ERROR.
 133 .TP
 134 .B MM_WARNING
 135 This value is printed as WARNING.
 136 .TP
 137 .B MM_INFO
 138 This value is printed as INFO.
 139 .PP
 140 The numeric values are between 0 and 4.
 141 Using
 142 .BR addseverity (3)
 143 or the environment variable
 144 .B SEV_LEVEL
 145 you can add more levels and strings to print.
 146 .SH ENVIRONMENT
 147 The environment variable
 148 .B MSGVERB
 149 ("message verbosity") can be used to suppress parts of
 150 the output to
 151 .IR stderr .
 152 (It does not influence output to the console.)
 153 When this variable is defined, is non-NULL, and is a colon-separated
 154 list of valid keywords, then only the parts of the message corresponding
 155 to these keywords is printed.
 156 Valid keywords are "label", "severity", "text", "action" and "tag".
 157 .PP
 158 The environment variable
 159 .B SEV_LEVEL
 160 can be used to introduce new severity levels.
 161 By default, only the five severity levels described
 162 above are available.
 163 Any other numeric value would make
 164 .BR fmtmsg ()
 165 print nothing.
 166 If the user puts
 167 .B SEV_LEVEL
 168 with a format like
 169 .sp
 170 .RS
 171 SEV_LEVEL=[description[:description[:...]]]
 172 .RE
 173 .sp
 174 in the environment of the process before the first call to
 175 .BR fmtmsg (),
 176 where each description is of the form
 177 .sp
 178 .RS
 179 severity-keyword,level,printstring
 180 .RE
 181 .sp
 182 then
 183 .BR fmtmsg ()
 184 will also accept the indicated values for the level (in addition to
 185 the standard levels 0-4), and use the indicated printstring when
 186 such a level occurs.
 187 .LP
 188 The severity-keyword part is not used by
 189 .BR fmtmsg ()
 190 but it has to be present.
 191 The level part is a string representation of a number.
 192 The numeric value must be a number greater than 4.
 193 This value must be used in the severity parameter of
 194 .BR fmtmsg ()
 195 to select this class.
 196 It is not possible to overwrite
 197 any of the predefined classes.
 198 The printstring
 199 is the string printed when a message of this class is processed by
 200 .BR fmtmsg ().
 201 .SH "RETURN VALUE"
 202 The function can return 4 values:
 203 .TP 12n
 204 .B MM_OK
 205 Everything went smooth.
 206 .TP
 207 .B MM_NOTOK
 208 Complete failure.
 209 .TP
 210 .B MM_NOMSG
 211 Error writing to
 212 .IR stderr .
 213 .TP
 214 .B MM_NOCON
 215 Error writing to the console.
 216 .SH "CONFORMING TO"
 217 The functions
 218 .BR fmtmsg ()
 219 and
 220 .BR addseverity (3),
 221 and environment variables
 222 .B MSGVERB
 223 and
 224 .B SEV_LEVEL
 225 come from System V.
 226 The function
 227 .BR fmtmsg ()
 228 and the environment variable
 229 .B MSGVERB
 230 are described in POSIX.1-2001.
 231 .SH NOTES
 232 System V and Unixware man pages tell us that these functions
 233 have been replaced by "pfmt() and addsev()" or by "pfmt(),
 234 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 235 .SH EXAMPLE
 236 .nf
 237 #include <stdio.h>
 238 #include <fmtmsg.h>
 239
 240 int
 241 main(void)
 242 {
 243     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 244     int err;
 245     err = fmtmsg(class, "util-linux:mount", MM_ERROR,
 246                 "unknown mount option", "See mount(8).",
 247                 "util-linux:mount:017");
 248     switch(err) {
 249     case MM_OK:
 250         break;
 251     case MM_NOTOK:
 252         printf("Nothing printed\en");
 253         break;
 254     case MM_NOMSG:
 255         printf("Nothing printed to stderr\en");
 256         break;
 257     case MM_NOCON:
 258         printf("No console output\en");
 259         break;
 260     default:
 261         printf("Unknown error from fmtmsg()\en");
 262     }
 263     exit(EXIT_SUCCESS);
 264 }
 265 .fi
 266 .PP
 267 The output should be:
 268 .nf
 269   util-linux:mount: ERROR: unknown mount option
 270   TO FIX: See mount(8).  util-linux:mount:017
 271 .fi
 272 and after
 273 .nf
 274   MSGVERB=text:action; export MSGVERB
 275 .fi
 276 the output becomes:
 277 .nf
 278   unknown mount option
 279   TO FIX: See mount(8).
 280 .fi
 281 .SH "SEE ALSO"
 282 .BR addseverity (3),
 283 .BR perror (3)