lib/libc/gen/fmtmsg.3

   1 .\"
   2 .\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org>
   3 .\" All rights reserved.
   4 .\"
   5 .\" Redistribution and use in source and binary forms, with or without
   6 .\" modification, are permitted provided that the following conditions
   7 .\" are met:
   8 .\" 1. Redistributions of source code must retain the above copyright
   9 .\"    notice, this list of conditions and the following disclaimer.
  10 .\" 2. Redistributions in binary form must reproduce the above copyright
  11 .\"    notice, this list of conditions and the following disclaimer in the
  12 .\"    documentation and/or other materials provided with the distribution.
  13 .\"
  14 .\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
  15 .\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  16 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
  17 .\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
  18 .\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
  19 .\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
  20 .\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  21 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
  22 .\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
  23 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
  24 .\" SUCH DAMAGE.
  25 .\"
  26 .\" $FreeBSD: src/lib/libc/gen/fmtmsg.3,v 1.4 2002/12/04 18:57:44 ru Exp $
  27 .\" $DragonFly: src/lib/libc/gen/fmtmsg.3,v 1.1 2008/10/06 21:01:37 swildner Exp $
  28 .\"
  29 .Dd October 6, 2008
  30 .Dt FMTMSG 3
  31 .Os
  32 .Sh NAME
  33 .Nm fmtmsg
  34 .Nd display a detailed diagnostic message
  35 .Sh LIBRARY
  36 .Lb libc
  37 .Sh SYNOPSIS
  38 .In fmtmsg.h
  39 .Ft int
  40 .Fo fmtmsg
  41 .Fa "long classification" "const char *label" "int severity"
  42 .Fa "const char *text" "const char *action" "const char *tag"
  43 .Fc
  44 .Sh DESCRIPTION
  45 The
  46 .Fn fmtmsg
  47 function displays a detailed diagnostic message, based on
  48 the supplied arguments, to
  49 .Dv stderr
  50 and/or the system console.
  51 .Pp
  52 The
  53 .Fa classification
  54 argument is the bitwise inclusive
  55 .Tn OR
  56 of zero or one of the manifest constants from
  57 each of the classification groups below.
  58 The Output classification group is an exception since both
  59 .Dv MM_PRINT
  60 and
  61 .Dv MM_CONSOLE
  62 may be specified.
  63 .Bl -tag -width indent
  64 .It Output
  65 .Bl -tag -width ".Dv MM_CONSOLE"
  66 .It Dv MM_PRINT
  67 Output should take place on
  68 .Dv stderr .
  69 .It Dv MM_CONSOLE
  70 Output should take place on the system console.
  71 .El
  72 .It "Source of Condition (Major)"
  73 .Bl -tag -width ".Dv MM_CONSOLE"
  74 .It Dv MM_HARD
  75 The source of the condition is hardware related.
  76 .It Dv MM_SOFT
  77 The source of the condition is software related.
  78 .It Dv MM_FIRM
  79 The source of the condition is firmware related.
  80 .El
  81 .It "Source of Condition (Minor)"
  82 .Bl -tag -width ".Dv MM_CONSOLE"
  83 .It Dv MM_APPL
  84 The condition was detected at the application level.
  85 .It Dv MM_UTIL
  86 The condition was detected at the utility level.
  87 .It Dv MM_OPSYS
  88 The condition was detected at the operating system level.
  89 .El
  90 .It Status
  91 .Bl -tag -width ".Dv MM_CONSOLE"
  92 .It Dv MM_RECOVER
  93 The application can recover from the condition.
  94 .It Dv MM_NRECOV
  95 The application is unable to recover from the condition.
  96 .El
  97 .El
  98 .Pp
  99 Alternatively, the
 100 .Dv MM_NULLMC
 101 manifest constant may be used to specify no classification.
 102 .Pp
 103 The
 104 .Fa label
 105 argument indicates the source of the message.
 106 It is made up of two fields separated by a colon
 107 .Pq Ql \&: .
 108 The first field can be up to 10 bytes,
 109 and the second field can be up to 14 bytes.
 110 The
 111 .Dv MM_NULLLBL
 112 manifest constant may be used to specify no label.
 113 .Pp
 114 The
 115 .Fa severity
 116 argument identifies the importance of the condition.
 117 One of the following manifest constants should be used for this argument.
 118 .Bl -tag -offset indent -width ".Dv MM_WARNING"
 119 .It Dv MM_HALT
 120 The application has confronted a serious fault and is halting.
 121 .It Dv MM_ERROR
 122 The application has detected a fault.
 123 .It Dv MM_WARNING
 124 The application has detected an unusual condition,
 125 that could be indicative of a problem.
 126 .It Dv MM_INFO
 127 The application is providing information about a non-error condition.
 128 .It Dv MM_NOSEV
 129 No severity level supplied.
 130 .El
 131 .Pp
 132 The
 133 .Fa text
 134 argument details the error condition that caused the message.
 135 There is no limit on the size of this character string.
 136 The
 137 .Dv MM_NULLTXT
 138 manifest constant may be used to specify no text.
 139 .Pp
 140 The
 141 .Fa action
 142 argument details how the error-recovery process should begin.
 143 Upon output,
 144 .Fn fmtmsg
 145 will prefix
 146 .Qq Li "TO FIX:"
 147 to the beginning of the
 148 .Fa action
 149 argument.
 150 The
 151 .Dv MM_NULLACT
 152 manifest constant may be used to specify no action.
 153 .Pp
 154 The
 155 .Fa tag
 156 argument should reference online documentation for the message.
 157 This usually includes the
 158 .Fa label
 159 and a unique identifying number.
 160 An example tag is
 161 .Qq Li BSD:ls:168 .
 162 The
 163 .Dv MM_NULLTAG
 164 manifest constant may be used to specify no tag.
 165 .Sh RETURN VALUES
 166 The
 167 .Fn fmtmsg
 168 function returns
 169 .Dv MM_OK
 170 upon success,
 171 .Dv MM_NOMSG
 172 to indicate output to
 173 .Dv stderr
 174 failed,
 175 .Dv MM_NOCON
 176 to indicate output to the system console failed, or
 177 .Dv MM_NOTOK
 178 to indicate output to
 179 .Dv stderr
 180 and the system console failed.
 181 .Sh ENVIRONMENT
 182 The
 183 .Ev MSGVERB
 184 (message verbosity)
 185 environment variable specifies which arguments to
 186 .Fn fmtmsg
 187 will be output to
 188 .Dv stderr ,
 189 and in which order.
 190 .Ev MSGVERB
 191 should be a colon
 192 .Pq Ql \&:
 193 separated list of identifiers.
 194 Valid identifiers include:
 195 .Li label , severity , text , action ,
 196 and
 197 .Li tag .
 198 If invalid identifiers are specified or incorrectly separated,
 199 the default message verbosity and ordering will be used.
 200 The default ordering is equivalent to a
 201 .Ev MSGVERB
 202 with a value of
 203 .Qq Li label:severity:text:action:tag .
 204 .Sh EXAMPLES
 205 The code:
 206 .Bd -literal -offset indent
 207 fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR,
 208     "illegal option -- z", "refer to manual", "BSD:ls:001");
 209 .Ed
 210 .Pp
 211 will output:
 212 .Bd -literal -offset indent
 213 BSD:ls: ERROR: illegal option -- z
 214 TO FIX: refer to manual BSD:ls:001
 215 .Ed
 216 .Pp
 217 to
 218 .Dv stderr .
 219 .Pp
 220 The same code, with
 221 .Ev MSGVERB
 222 set to
 223 .Qq Li "text:severity:action:tag" ,
 224 produces:
 225 .Bd -literal -offset indent
 226 illegal option -- z: ERROR
 227 TO FIX: refer to manual BSD:ls:001
 228 .Ed
 229 .Sh SEE ALSO
 230 .Xr err 3 ,
 231 .Xr exit 3 ,
 232 .Xr strerror 3
 233 .Sh STANDARDS
 234 The
 235 .Fn fmtmsg
 236 function conforms to
 237 .St -p1003.1-2001 .
 238 .Sh HISTORY
 239 The
 240 .Fn fmtmsg
 241 function first appeared in
 242 .Fx 5.0 .
 243 It was imported into
 244 .Dx 2.1 .
 245 .Sh BUGS
 246 Specifying
 247 .Dv MM_NULLMC
 248 for the
 249 .Fa classification
 250 argument makes little sense, since without an output specified,
 251 .Fn fmtmsg
 252 is unable to do anything useful.
 253 .Pp
 254 In order for
 255 .Fn fmtmsg
 256 to output to the system console, the effective
 257 user must have appropriate permission to write to
 258 .Pa /dev/console .
 259 This means that on most systems
 260 .Fn fmtmsg
 261 will return
 262 .Dv MM_NOCON
 263 unless the effective user is root.