lib/libc/gen/fmtmsg.3

   1 .\"     $NetBSD: fmtmsg.3,v 1.7 2011/04/11 05:59:11 jruoho Exp $
   2 .\"
   3 .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
   4 .\" All rights reserved.
   5 .\"
   6 .\" This code is derived from software contributed to The NetBSD Foundation
   7 .\" by Klaus Klein.
   8 .\"
   9 .\" Redistribution and use in source and binary forms, with or without
  10 .\" modification, are permitted provided that the following conditions
  11 .\" are met:
  12 .\" 1. Redistributions of source code must retain the above copyright
  13 .\"    notice, this list of conditions and the following disclaimer.
  14 .\" 2. Redistributions in binary form must reproduce the above copyright
  15 .\"    notice, this list of conditions and the following disclaimer in the
  16 .\"    documentation and/or other materials provided with the distribution.
  17 .\"
  18 .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
  19 .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
  20 .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  21 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
  22 .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
  23 .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
  24 .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
  25 .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
  26 .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  27 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
  28 .\" POSSIBILITY OF SUCH DAMAGE.
  29 .\"
  30 .Dd April 11, 2011
  31 .Dt FMTMSG 3
  32 .Os
  33 .Sh NAME
  34 .Nm fmtmsg
  35 .Nd format and display a message
  36 .Sh LIBRARY
  37 .Lb libc
  38 .Sh SYNOPSIS
  39 .In fmtmsg.h
  40 .Ft int
  41 .Fn fmtmsg "long classification" "const char *label" "int severity" "const char *text" "const char *action" "const char *tag"
  42 .Sh DESCRIPTION
  43 The
  44 .Fn fmtmsg
  45 function can be used to display messages in the specified format.
  46 Messages may be written either to standard error, to the console, or both.
  47 .Pp
  48 A formatted message consists of up to five components specified in
  49 .Fa label ,
  50 .Fa severity ,
  51 .Fa text ,
  52 .Fa action
  53 and
  54 .Fa tag .
  55 Further information such as the origin of the message, the recoverability
  56 from the condition causing the message and where to display the message
  57 is specified in
  58 .Fa classification .
  59 .Ss Classification
  60 The
  61 .Fa classification
  62 argument consists of a major classification and several sub-classifications.
  63 It has no effect on the content of the message displayed.
  64 With the exception of the display sub-classification, only a single identifier
  65 may be specified for each (sub-)classification.
  66 The following classifications
  67 are available:
  68 .Bl -tag -width "XXX"
  69 .It Em Major classifications
  70 The source of the condition.
  71 Available identifiers are:
  72 .Dv MM_HARD
  73 (hardware),
  74 .Dv MM_SOFT
  75 (software), and
  76 .Dv MM_FIRM
  77 (firmware).
  78 .It Em Message source sub-classifications
  79 The type of software detecting the condition.
  80 Available identifiers are:
  81 .Dv MM_APPL
  82 (application),
  83 .Dv MM_UTIL
  84 (utility), and
  85 .Dv MM_OPSYS
  86 (operating system).
  87 .It Em Display sub-classifications
  88 The displays the formatted messages is to be written to.
  89 Available identifiers are:
  90 .Dv MM_PRINT
  91 (standard error stream) and
  92 .Dv MM_CONSOLE
  93 (system console).
  94 .It Em Status sub-classifications
  95 The capability of the calling software to recover from the condition.
  96 Available identifiers are:
  97 .Dv MM_RECOVER
  98 (recoverable) and
  99 .Dv MM_NRECOV
 100 (non-recoverable).
 101 .El
 102 .Pp
 103 If no
 104 .Fa classification
 105 is to be supplied,
 106 .Dv MM_NULLMC
 107 must be specified.
 108 .Ss Label
 109 The
 110 .Fa label
 111 argument identifies the source of the message.
 112 It consists of two fields separated by a colon (:).
 113 The first field is up to 10 characters, the second is up to 14 characters.
 114 .Pp
 115 If no
 116 .Fa label
 117 is to be supplied,
 118 .Dv MM_NULLLBL
 119 must be specified.
 120 .Ss Severity
 121 The seriousness of the condition causing the message.
 122 The following
 123 .Fa severity
 124 levels are available:
 125 .Bl -tag -width MM_WARNING -offset indent
 126 .It Dv MM_HALT
 127 The software has encountered a severe fault and is halting.
 128 .It Dv MM_ERROR
 129 The software has encountered a fault.
 130 .It Dv MM_WARNING
 131 The software has encountered an unusual non-fault condition.
 132 .It Dv MM_INFO
 133 The software informs about a non-error condition.
 134 .El
 135 .Pp
 136 If no
 137 .Fa severity
 138 level is to be supplied,
 139 .Dv MM_NOSEV
 140 must be specified.
 141 .Ss Text
 142 The description of the condition the software encountered.
 143 The character
 144 string is not limited to a specific size.
 145 .Pp
 146 If no
 147 .Fa text
 148 is to be supplied,
 149 .Dv MM_NOTXT
 150 must be specified.
 151 .Ss Action
 152 The first step to be taken to recover from the condition the software
 153 encountered; it will be preceded by the prefix
 154 .Dq TO FIX: .
 155 The character string is not limited to a specific size.
 156 .Pp
 157 If no
 158 .Fa action
 159 is to be supplied,
 160 .Dv MM_NOACT
 161 must be specified.
 162 .Ss Tag
 163 The on-line documentation which provides further information about the
 164 condition and the message, such as
 165 .Dq Xr fmtmsg 3 .
 166 The character string is not limited to a specific size.
 167 .Pp
 168 If no
 169 .Fa tag
 170 is to be supplied,
 171 .Dv MM_NOTAG
 172 must be specified.
 173 .Pp
 174 Further effect on the formatting of the message as displayed on the
 175 standard error stream (but not on the system console!) may be taken by
 176 setting the
 177 .Ev MSGVERB
 178 environment variable, which selects the subset of message components
 179 to be printed.
 180 It consists of a colon-separated list of the optional keywords
 181 .Fa label ,
 182 .Fa severity ,
 183 .Fa text ,
 184 .Fa action ,
 185 and
 186 .Fa tag ,
 187 which correspond to the arguments to
 188 .Fn fmtmsg
 189 with the same names.
 190 If
 191 .Ev MSGVERB
 192 is either not set or malformed (containing empty or unknown keywords),
 193 its content is ignored an all message components will be selected.
 194 .Pp
 195 Note that displaying a message on the system console may fail due to
 196 inappropriate privileges or a non-permissive file mode of the console device.
 197 .Sh RETURN VALUES
 198 The
 199 .Fn fmtmsg
 200 function returns one of the following values:
 201 .Bl -tag -width MM_NOTOKXXX
 202 .It Dv MM_OK
 203 The function succeeded.
 204 .It Dv MM_NOTOK
 205 The function failed completely.
 206 .It Dv MM_NOMSG
 207 The function was unable to generate a message on standard error,
 208 but otherwise succeeded.
 209 .It Dv MM_NOCOM
 210 The function was unable to generate a message on the console,
 211 but otherwise succeeded.
 212 .El
 213 .Sh SEE ALSO
 214 .Xr printf 3 ,
 215 .Xr syslog 3
 216 .Sh STANDARDS
 217 The
 218 .Fn fmtmsg
 219 function conforms to
 220 .St -xsh5 .