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