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 2008-06-14 "" "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 CONFORMING TO
 226 The functions
 227 .BR fmtmsg ()
 228 and
 229 .BR addseverity (3),
 230 and environment variables
 231 .B MSGVERB
 232 and
 233 .B SEV_LEVEL
 234 come from System V.
 235 The function
 236 .BR fmtmsg ()
 237 and the environment variable
 238 .B MSGVERB
 239 are described in POSIX.1-2001.
 240 .SH NOTES
 241 System V and UnixWare man pages tell us that these functions
 242 have been replaced by "pfmt() and addsev()" or by "pfmt(),
 243 vpfmt(), lfmt(), and vlfmt()", and will be removed later.
 244 .SH EXAMPLE
 245 .nf
 246 #include <stdio.h>
 247 #include <stdlib.h>
 248 #include <fmtmsg.h>
 249
 250 int
 251 main(void)
 252 {
 253     long class = MM_PRINT | MM_SOFT | MM_OPSYS | MM_RECOVER;
 254     int err;
 255
 256     err = fmtmsg(class, "util\-linux:mount", MM_ERROR,
 257                 "unknown mount option", "See mount(8).",
 258                 "util\-linux:mount:017");
 259     switch (err) {
 260     case MM_OK:
 261         break;
 262     case MM_NOTOK:
 263         printf("Nothing printed\en");
 264         break;
 265     case MM_NOMSG:
 266         printf("Nothing printed to stderr\en");
 267         break;
 268     case MM_NOCON:
 269         printf("No console output\en");
 270         break;
 271     default:
 272         printf("Unknown error from fmtmsg()\en");
 273     }
 274     exit(EXIT_SUCCESS);
 275 }
 276 .fi
 277 .PP
 278 The output should be:
 279 .nf
 280
 281     util\-linux:mount: ERROR: unknown mount option
 282     TO FIX: See mount(8).  util\-linux:mount:017
 283
 284 .fi
 285 and after
 286 .nf
 287
 288     MSGVERB=text:action; export MSGVERB
 289
 290 .fi
 291 the output becomes:
 292 .nf
 293
 294     unknown mount option
 295     TO FIX: See mount(8).
 296 .fi
 297 .SH SEE ALSO
 298 .BR addseverity (3),
 299 .BR perror (3)