share/man/man1/fmtmsg.1

   1 '\" te
   2 .\"  Copyright 1989 AT&T  Copyright (c) 1994, Sun Microsystems, Inc.  All Rights Reserved
   3 .\" 2003, Sun Microsystems, Inc.  All Rights Reserved
   4 .\" The contents of this file are subject to the terms of the Common Development and Distribution License (the "License").  You may not use this file except in compliance with the License.
   5 .\" You can obtain a copy of the license at usr/src/OPENSOLARIS.LICENSE or http://www.opensolaris.org/os/licensing.  See the License for the specific language governing permissions and limitations under the License.
   6 .\" When distributing Covered Code, include this CDDL HEADER in each file and include the License file at usr/src/OPENSOLARIS.LICENSE.  If applicable, add the following below this CDDL HEADER, with the fields enclosed by brackets "[]" replaced with your own identifying information: Portions Copyright [yyyy] [name of copyright owner]
   7 .TH FMTMSG 1 "Jul 20, 1994"
   8 .SH NAME
   9 fmtmsg \- display a message on stderr or system console
  10 .SH SYNOPSIS
  11 .LP
  12 .nf
  13 \fBfmtmsg\fR [\fB-c\fR \fIclass\fR] [\fB-u\fR \fIsubclass\fR] [\fB-l\fR \fIlabel\fR] [\fB-s\fR \fIseverity\fR]
  14      [\fB-t\fR \fItag\fR] [\fB-a\fR \fIaction\fR] \fItext\fR
  15 .fi
  16
  17 .SH DESCRIPTION
  18 .sp
  19 .LP
  20 Based on a message's classification component, the \fBfmtmsg\fR utility either
  21 writes a formatted message to \fBstderr\fR or writes a formatted message to the
  22 console.
  23 .sp
  24 .LP
  25 A formatted message consists of up to five standard components (see environment
  26 variable \fBMSGVERB\fR in the ENVIRONMENT VARIABLES section of this page). The
  27 classification and subclass components are not displayed as part of the
  28 standard message, but rather define the source of the message and direct the
  29 display of the formatted message.
  30 .SH OPTIONS
  31 .sp
  32 .LP
  33 The following options are supported:
  34 .sp
  35 .ne 2
  36 .na
  37 \fB\fB-c\fR \fIclass\fR \fR
  38 .ad
  39 .RS 16n
  40 Describes the source of the message. Valid keywords are:
  41 .sp
  42 .ne 2
  43 .na
  44 \fB\fBhard\fR \fR
  45 .ad
  46 .RS 9n
  47 The source of the condition is hardware.
  48 .RE
  49
  50 .sp
  51 .ne 2
  52 .na
  53 \fB\fBsoft\fR \fR
  54 .ad
  55 .RS 9n
  56 The source of the condition is software.
  57 .RE
  58
  59 .sp
  60 .ne 2
  61 .na
  62 \fB\fBfirm\fR \fR
  63 .ad
  64 .RS 9n
  65 The source of the condition is firmware.
  66 .RE
  67
  68 .RE
  69
  70 .sp
  71 .ne 2
  72 .na
  73 \fB\fB-u\fR \fIsubclass\fR \fR
  74 .ad
  75 .RS 16n
  76 A list of keywords (separated by commas) that further defines the message and
  77 directs the display of the message. Valid keywords are:
  78 .sp
  79 .ne 2
  80 .na
  81 \fB\fBappl\fR \fR
  82 .ad
  83 .RS 12n
  84 The condition originated in an application. This keyword should not be used in
  85 combination with either \fButil\fR or \fBopsys\fR.
  86 .RE
  87
  88 .sp
  89 .ne 2
  90 .na
  91 \fB\fButil\fR \fR
  92 .ad
  93 .RS 12n
  94 The condition originated in a utility. This keyword should not be used in
  95 combination with either \fBappl\fR or \fBopsys\fR.
  96 .RE
  97
  98 .sp
  99 .ne 2
 100 .na
 101 \fB\fBopsys\fR \fR
 102 .ad
 103 .RS 12n
 104 The message originated in the kernel. This keyword should not be used in
 105 combination with either \fBappl\fR or \fButil\fR.
 106 .RE
 107
 108 .sp
 109 .ne 2
 110 .na
 111 \fB\fBrecov\fR \fR
 112 .ad
 113 .RS 12n
 114 The application will recover from the condition. This keyword should not be
 115 used in combination with \fBnrecov\fR.
 116 .RE
 117
 118 .sp
 119 .ne 2
 120 .na
 121 \fB\fBnrecov\fR \fR
 122 .ad
 123 .RS 12n
 124 The application will not recover from the condition. This keyword should not be
 125 used in combination with \fBrecov\fR.
 126 .RE
 127
 128 .sp
 129 .ne 2
 130 .na
 131 \fB\fBprint\fR \fR
 132 .ad
 133 .RS 12n
 134 Print the message to the standard error stream \fBstderr\fR.
 135 .RE
 136
 137 .sp
 138 .ne 2
 139 .na
 140 \fB\fBconsole\fR \fR
 141 .ad
 142 .RS 12n
 143 Write the message to the system console. \fBprint\fR, \fBconsole\fR, or both
 144 may be used.
 145 .RE
 146
 147 .RE
 148
 149 .sp
 150 .ne 2
 151 .na
 152 \fB\fB-l\fR \fIlabel\fR \fR
 153 .ad
 154 .RS 16n
 155 Identifies the source of the message.
 156 .RE
 157
 158 .sp
 159 .ne 2
 160 .na
 161 \fB\fB-s\fR \fIseverity\fR \fR
 162 .ad
 163 .RS 16n
 164 Indicates the seriousness of the error. The keywords and definitions of the
 165 standard levels of \fIseverity\fR are:
 166 .sp
 167 .ne 2
 168 .na
 169 \fB\fBhalt\fR \fR
 170 .ad
 171 .RS 9n
 172 The application has encountered a severe fault and is halting.
 173 .RE
 174
 175 .sp
 176 .ne 2
 177 .na
 178 \fB\fBerror\fR\fR
 179 .ad
 180 .RS 9n
 181 The application has detected a fault.
 182 .RE
 183
 184 .sp
 185 .ne 2
 186 .na
 187 \fB\fBwarn\fR\fR
 188 .ad
 189 .RS 9n
 190 The application has detected a condition that is out of the ordinary and might
 191 be a problem.
 192 .RE
 193
 194 .sp
 195 .ne 2
 196 .na
 197 \fB\fBinfo\fR \fR
 198 .ad
 199 .RS 9n
 200 The application is providing information about a condition that is not in
 201 error.
 202 .RE
 203
 204 .RE
 205
 206 .sp
 207 .ne 2
 208 .na
 209 \fB\fB-t\fR \fItag\fR \fR
 210 .ad
 211 .RS 16n
 212 The string containing an identifier for the message.
 213 .RE
 214
 215 .sp
 216 .ne 2
 217 .na
 218 \fB\fB-a\fR \fIaction\fR \fR
 219 .ad
 220 .RS 16n
 221 A text string describing the first step in the error recovery process. This
 222 string must be written so that the entire \fIaction\fR argument is interpreted
 223 as a single argument. \fBfmtmsg\fR precedes each action string with the \fBTO
 224 FIX:\fR prefix.
 225 .RE
 226
 227 .sp
 228 .ne 2
 229 .na
 230 \fB\fItext\fR \fR
 231 .ad
 232 .RS 16n
 233 A text string describing the condition. Must be written so that the entire
 234 \fItext\fR argument is interpreted as a single argument.
 235 .RE
 236
 237 .SH EXAMPLES
 238 .LP
 239 \fBExample 1 \fRStandard message format
 240 .sp
 241 .LP
 242 The following example of \fBfmtmsg\fR produces a complete message in the
 243 standard message format and displays it to the standard error stream.
 244
 245 .sp
 246 .in +2
 247 .nf
 248 example% \fBfmtmsg -c soft -u recov,print,appl -l UX:cat \e
 249      -s error -t UX:cat:001 -a "refer to manual" "invalid syntax"\fR
 250 .fi
 251 .in -2
 252 .sp
 253
 254 .sp
 255 .LP
 256 produces:
 257
 258 .sp
 259 .in +2
 260 .nf
 261 UX:cat: ERROR: invalid syntax
 262 TO FIX: refer to manual   UX:cat:138
 263 .fi
 264 .in -2
 265 .sp
 266
 267 .LP
 268 \fBExample 2 \fRUsing MSGVERB
 269 .sp
 270 .LP
 271 When the environment variable \fBMSGVERB\fR is set as follows:
 272
 273 .sp
 274 .in +2
 275 .nf
 276 \fBMSGVERB=severity:text:action\fR
 277 .fi
 278 .in -2
 279 .sp
 280
 281 .sp
 282 .LP
 283 and Example 1 is used, \fBfmtmsg\fR produces:
 284
 285 .sp
 286 .in +2
 287 .nf
 288 ERROR: invalid syntax
 289 TO FIX: refer to manual
 290 .fi
 291 .in -2
 292 .sp
 293
 294 .LP
 295 \fBExample 3 \fRUsing SEV_LEVEL
 296 .sp
 297 .LP
 298 When the environment variable \fBSEV_LEVEL\fR is set as follows:
 299
 300 .sp
 301 .in +2
 302 .nf
 303 \fBSEV_LEVEL=note,5,NOTE\fR
 304 .fi
 305 .in -2
 306 .sp
 307
 308 .sp
 309 .LP
 310 the following \fBfmtmsg\fR command:
 311
 312 .sp
 313 .in +2
 314 .nf
 315 example% \fBfmtmsg -c soft -u print -l UX:cat -s note \e
 316      -a "refer to manual" "invalid syntax"\fR
 317 .fi
 318 .in -2
 319 .sp
 320
 321 .sp
 322 .LP
 323 produces:
 324
 325 .sp
 326 .in +2
 327 .nf
 328 NOTE: invalid syntax
 329 TO FIX: refer to manual
 330 .fi
 331 .in -2
 332 .sp
 333
 334 .sp
 335 .LP
 336 and displays the message on \fBstderr\fR.
 337
 338 .SH ENVIRONMENT VARIABLES
 339 .sp
 340 .LP
 341 The environment variables \fBMSGVERB\fR and \fBSEV_LEVEL\fR control the
 342 behavior of \fBfmtmsg\fR. \fBMSGVERB\fR is set by the administrator in the
 343 \fB/etc/profile\fR for the system. Users can override the value of
 344 \fBMSGVERB\fR set by the system by resetting \fBMSGVERB\fR in their own
 345 \fB\&.profile\fR files or by changing the value in their current shell session.
 346 \fBSEV_LEVEL\fR can be used in shell scripts.
 347 .sp
 348 .LP
 349 \fBMSGVERB\fR tells \fBfmtmsg\fR which message components to select when
 350 writing messages to \fBstderr\fR. The value of \fBMSGVERB\fR is a
 351 colon-separated list of optional keywords. \fBMSGVERB\fR can be set as follows:
 352 .sp
 353 .in +2
 354 .nf
 355 \fBMSGVERB=[\fIkeyword\fR[:\fIkeyword\fR[:...]]]
 356 export MSGVERB\fR
 357 .fi
 358 .in -2
 359 .sp
 360
 361 .sp
 362 .LP
 363 Valid \fIkeyword\fRs are: \fBlabel\fR, \fBseverity\fR, \fBtext\fR,
 364 \fBaction\fR, and \fBtag\fR. If \fBMSGVERB\fR contains a keyword for a
 365 component and the component's value is not the component's null value,
 366 \fBfmtmsg\fR includes that component in the message when writing the message to
 367 \fBstderr\fR. If \fBMSGVERB\fR does not include a keyword for a message
 368 component, that component is not included in the display of the message. The
 369 keywords may appear in any order. If \fBMSGVERB\fR is not defined, if its value
 370 is the null string, if its value is not of the correct format, or if it
 371 contains keywords other than the valid ones listed above, \fBfmtmsg\fR selects
 372 all components.
 373 .sp
 374 .LP
 375 \fBMSGVERB\fR affects only which message components are selected for display.
 376 All message components are included in console messages.
 377 .sp
 378 .LP
 379 \fBSEV_LEVEL\fR defines severity levels and associates print strings with them
 380 for use by \fBfmtmsg\fR. The standard severity levels shown below cannot be
 381 modified. Additional severity levels can be defined, redefined, and removed.
 382 .sp
 383 .ne 2
 384 .na
 385 \fB\fB0\fR \fR
 386 .ad
 387 .RS 6n
 388 (no severity is used)
 389 .RE
 390
 391 .sp
 392 .ne 2
 393 .na
 394 \fB\fB1\fR \fR
 395 .ad
 396 .RS 6n
 397 \fBHALT\fR
 398 .RE
 399
 400 .sp
 401 .ne 2
 402 .na
 403 \fB\fB2\fR \fR
 404 .ad
 405 .RS 6n
 406 \fBERROR\fR
 407 .RE
 408
 409 .sp
 410 .ne 2
 411 .na
 412 \fB\fB3\fR \fR
 413 .ad
 414 .RS 6n
 415 \fBWARNING\fR
 416 .RE
 417
 418 .sp
 419 .ne 2
 420 .na
 421 \fB\fB4\fR \fR
 422 .ad
 423 .RS 6n
 424 \fBINFO\fR
 425 .RE
 426
 427 .sp
 428 .LP
 429 \fBSEV_LEVEL\fR is set as follows:
 430 .sp
 431 .LP
 432 \fIdescription\fR is a comma-separated list containing three fields:
 433 .sp
 434 .in +2
 435 .nf
 436 \fBSEV_LEVEL=   [\fIdescription\fR[:\fIdescription\fR[:...]]]
 437 export SEV_LEVEL\fR
 438 .fi
 439 .in -2
 440 .sp
 441
 442 .sp
 443 .LP
 444 \fIdescription\fR=\fIseverity_keyword\fR, \fIlevel\fR, \fIprintstring\fR
 445 .sp
 446 .LP
 447 \fIseverity_keyword\fR is a character string used as the keyword with the
 448 \fB-s\fR \fIseverity\fR option to \fBfmtmsg\fR.
 449 .sp
 450 .LP
 451 \fIlevel\fR is a character string that evaluates to a positive integer (other
 452 than \fB0\fR, \fB1\fR, \fB2\fR, \fB3\fR, or \fB4\fR, which are reserved for the
 453 standard severity levels). If the keyword \fIseverity_keyword\fR is used,
 454 \fIlevel\fR is the severity value passed on to \fBfmtmsg\fR(3C).
 455 .sp
 456 .LP
 457 \fIprintstring\fR is the character string used by \fBfmtmsg\fR in the standard
 458 message format whenever the severity value \fIlevel\fR is used.
 459 .sp
 460 .LP
 461 If \fBSEV_LEVEL\fR is not defined, or if its value is null, no severity levels
 462 other than the defaults are available. If a \fIdescription\fR in the colon
 463 separated list is not a comma separated list containing three fields, or if the
 464 second field of a comma separated list does not evaluate to a positive integer,
 465 that \fIdescription\fR in the colon separated list is ignored.
 466 .SH EXIT STATUS
 467 .sp
 468 .LP
 469 The following exit values are returned:
 470 .sp
 471 .ne 2
 472 .na
 473 \fB\fB0\fR \fR
 474 .ad
 475 .RS 7n
 476 All the requested functions were executed successfully.
 477 .RE
 478
 479 .sp
 480 .ne 2
 481 .na
 482 \fB\fB1\fR \fR
 483 .ad
 484 .RS 7n
 485 The command contains a syntax error, an invalid option, or an invalid argument
 486 to an option.
 487 .RE
 488
 489 .sp
 490 .ne 2
 491 .na
 492 \fB\fB2\fR \fR
 493 .ad
 494 .RS 7n
 495 The function executed with partial success, however the message was not
 496 displayed on \fBstderr\fR.
 497 .RE
 498
 499 .sp
 500 .ne 2
 501 .na
 502 \fB\fB4\fR \fR
 503 .ad
 504 .RS 7n
 505 The function executed with partial success; however, the message was not
 506 displayed on the system console.
 507 .RE
 508
 509 .sp
 510 .ne 2
 511 .na
 512 \fB\fB32\fR \fR
 513 .ad
 514 .RS 7n
 515 No requested functions were executed successfully.
 516 .RE
 517
 518 .SH SEE ALSO
 519 .sp
 520 .LP
 521 \fBaddseverity\fR(3C), \fBfmtmsg\fR(3C), \fBattributes\fR(5)