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 .Dd August 5, 2002
  27 .Dt FMTMSG 3
  28 .Os
  29 .Sh NAME
  30 .Nm fmtmsg
  31 .Nd display a detailed diagnostic message
  32 .Sh LIBRARY
  33 .Lb libc
  34 .Sh SYNOPSIS
  35 .In fmtmsg.h
  36 .Ft int
  37 .Fo fmtmsg
  38 .Fa "long classification" "const char *label" "int severity"
  39 .Fa "const char *text" "const char *action" "const char *tag"
  40 .Fc
  41 .Sh DESCRIPTION
  42 The
  43 .Fn fmtmsg
  44 function displays a detailed diagnostic message, based on
  45 the supplied arguments, to
  46 .Dv stderr
  47 and/or the system console.
  48 .Pp
  49 The
  50 .Fa classification
  51 argument is the bitwise inclusive
  52 .Tn OR
  53 of zero or one of the manifest constants from
  54 each of the classification groups below.
  55 The Output classification group is an exception since both
  56 .Dv MM_PRINT
  57 and
  58 .Dv MM_CONSOLE
  59 may be specified.
  60 .Bl -tag -width indent
  61 .It Output
  62 .Bl -tag -width ".Dv MM_CONSOLE"
  63 .It Dv MM_PRINT
  64 Output should take place on
  65 .Dv stderr .
  66 .It Dv MM_CONSOLE
  67 Output should take place on the system console.
  68 .El
  69 .It "Source of Condition (Major)"
  70 .Bl -tag -width ".Dv MM_CONSOLE"
  71 .It Dv MM_HARD
  72 The source of the condition is hardware related.
  73 .It Dv MM_SOFT
  74 The source of the condition is software related.
  75 .It Dv MM_FIRM
  76 The source of the condition is firmware related.
  77 .El
  78 .It "Source of Condition (Minor)"
  79 .Bl -tag -width ".Dv MM_CONSOLE"
  80 .It Dv MM_APPL
  81 The condition was detected at the application level.
  82 .It Dv MM_UTIL
  83 The condition was detected at the utility level.
  84 .It Dv MM_OPSYS
  85 The condition was detected at the operating system level.
  86 .El
  87 .It Status
  88 .Bl -tag -width ".Dv MM_CONSOLE"
  89 .It Dv MM_RECOVER
  90 The application can recover from the condition.
  91 .It Dv MM_NRECOV
  92 The application is unable to recover from the condition.
  93 .El
  94 .El
  95 .Pp
  96 Alternatively, the
  97 .Dv MM_NULLMC
  98 manifest constant may be used to specify no classification.
  99 .Pp
 100 The
 101 .Fa label
 102 argument indicates the source of the message.
 103 It is made up of two fields separated by a colon
 104 .Pq Ql \&: .
 105 The first field can be up to 10 bytes,
 106 and the second field can be up to 14 bytes.
 107 The
 108 .Dv MM_NULLLBL
 109 manifest constant may be used to specify no label.
 110 .Pp
 111 The
 112 .Fa severity
 113 argument identifies the importance of the condition.
 114 One of the following manifest constants should be used for this argument.
 115 .Bl -tag -offset indent -width ".Dv MM_WARNING"
 116 .It Dv MM_HALT
 117 The application has confronted a serious fault and is halting.
 118 .It Dv MM_ERROR
 119 The application has detected a fault.
 120 .It Dv MM_WARNING
 121 The application has detected an unusual condition,
 122 that could be indicative of a problem.
 123 .It Dv MM_INFO
 124 The application is providing information about a non-error condition.
 125 .It Dv MM_NOSEV
 126 No severity level supplied.
 127 .El
 128 .Pp
 129 The
 130 .Fa text
 131 argument details the error condition that caused the message.
 132 There is no limit on the size of this character string.
 133 The
 134 .Dv MM_NULLTXT
 135 manifest constant may be used to specify no text.
 136 .Pp
 137 The
 138 .Fa action
 139 argument details how the error-recovery process should begin.
 140 Upon output,
 141 .Fn fmtmsg
 142 will prefix
 143 .Qq Li "TO FIX:"
 144 to the beginning of the
 145 .Fa action
 146 argument.
 147 The
 148 .Dv MM_NULLACT
 149 manifest constant may be used to specify no action.
 150 .Pp
 151 The
 152 .Fa tag
 153 argument should reference online documentation for the message.
 154 This usually includes the
 155 .Fa label
 156 and a unique identifying number.
 157 An example tag is
 158 .Qq Li BSD:ls:168 .
 159 The
 160 .Dv MM_NULLTAG
 161 manifest constant may be used to specify no tag.
 162 .Sh RETURN VALUES
 163 The
 164 .Fn fmtmsg
 165 function returns
 166 .Dv MM_OK
 167 upon success,
 168 .Dv MM_NOMSG
 169 to indicate output to
 170 .Dv stderr
 171 failed,
 172 .Dv MM_NOCON
 173 to indicate output to the system console failed, or
 174 .Dv MM_NOTOK
 175 to indicate output to
 176 .Dv stderr
 177 and the system console failed.
 178 .Sh ENVIRONMENT
 179 The
 180 .Ev MSGVERB
 181 (message verbosity)
 182 environment variable specifies which arguments to
 183 .Fn fmtmsg
 184 will be output to
 185 .Dv stderr ,
 186 and in which order.
 187 .Ev MSGVERB
 188 should be a colon
 189 .Pq Ql \&:
 190 separated list of identifiers.
 191 Valid identifiers include:
 192 .Li label , severity , text , action ,
 193 and
 194 .Li tag .
 195 If invalid identifiers are specified or incorrectly separated,
 196 the default message verbosity and ordering will be used.
 197 The default ordering is equivalent to a
 198 .Ev MSGVERB
 199 with a value of
 200 .Qq Li label:severity:text:action:tag .
 201 .Sh EXAMPLES
 202 The code:
 203 .Bd -literal -offset indent
 204 fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR,
 205     "illegal option -- z", "refer to manual", "BSD:ls:001");
 206 .Ed
 207 .Pp
 208 will output:
 209 .Bd -literal -offset indent
 210 BSD:ls: ERROR: illegal option -- z
 211 TO FIX: refer to manual BSD:ls:001
 212 .Ed
 213 .Pp
 214 to
 215 .Dv stderr .
 216 .Pp
 217 The same code, with
 218 .Ev MSGVERB
 219 set to
 220 .Qq Li "text:severity:action:tag" ,
 221 produces:
 222 .Bd -literal -offset indent
 223 illegal option -- z: ERROR
 224 TO FIX: refer to manual BSD:ls:001
 225 .Ed
 226 .Sh SEE ALSO
 227 .Xr err 3 ,
 228 .Xr exit 3 ,
 229 .Xr strerror 3
 230 .Sh STANDARDS
 231 The
 232 .Fn fmtmsg
 233 function conforms to
 234 .St -p1003.1-2001 .
 235 .Sh HISTORY
 236 The
 237 .Fn fmtmsg
 238 function first appeared in
 239 .Fx 5.0 .
 240 .Sh BUGS
 241 Specifying
 242 .Dv MM_NULLMC
 243 for the
 244 .Fa classification
 245 argument makes little sense, since without an output specified,
 246 .Fn fmtmsg
 247 is unable to do anything useful.
 248 .Pp
 249 In order for
 250 .Fn fmtmsg
 251 to output to the system console, the effective
 252 user must have appropriate permission to write to
 253 .Pa /dev/console .
 254 This means that on most systems
 255 .Fn fmtmsg
 256 will return
 257 .Dv MM_NOCON
 258 unless the effective user is root.