2 .\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org>
3 .\" All rights reserved.
5 .\" Redistribution and use in source and binary forms, with or without
6 .\" modification, are permitted provided that the following conditions
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.
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
31 .Nd display a detailed diagnostic message
38 .Fa "long classification" "const char *label" "int severity"
39 .Fa "const char *text" "const char *action" "const char *tag"
44 function displays a detailed diagnostic message, based on
45 the supplied arguments, to
47 and/or the system console.
51 argument is the bitwise inclusive
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
60 .Bl -tag -width indent
62 .Bl -tag -width ".Dv MM_CONSOLE"
64 Output should take place on
67 Output should take place on the system console.
69 .It "Source of Condition (Major)"
70 .Bl -tag -width ".Dv MM_CONSOLE"
72 The source of the condition is hardware related.
74 The source of the condition is software related.
76 The source of the condition is firmware related.
78 .It "Source of Condition (Minor)"
79 .Bl -tag -width ".Dv MM_CONSOLE"
81 The condition was detected at the application level.
83 The condition was detected at the utility level.
85 The condition was detected at the operating system level.
88 .Bl -tag -width ".Dv MM_CONSOLE"
90 The application can recover from the condition.
92 The application is unable to recover from the condition.
98 manifest constant may be used to specify no classification.
102 argument indicates the source of the message.
103 It is made up of two fields separated by a colon
105 The first field can be up to 10 bytes,
106 and the second field can be up to 14 bytes.
109 manifest constant may be used to specify no label.
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"
117 The application has confronted a serious fault and is halting.
119 The application has detected a fault.
121 The application has detected an unusual condition,
122 that could be indicative of a problem.
124 The application is providing information about a non-error condition.
126 No severity level supplied.
131 argument details the error condition that caused the message.
132 There is no limit on the size of this character string.
135 manifest constant may be used to specify no text.
139 argument details how the error-recovery process should begin.
144 to the beginning of the
149 manifest constant may be used to specify no action.
153 argument should reference online documentation for the message.
154 This usually includes the
156 and a unique identifying number.
161 manifest constant may be used to specify no tag.
169 to indicate output to
173 to indicate output to the system console failed, or
175 to indicate output to
177 and the system console failed.
182 environment variable specifies which arguments to
190 separated list of identifiers.
191 Valid identifiers include:
192 .Li label , severity , text , action ,
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
200 .Qq Li label:severity:text:action:tag .
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");
209 .Bd -literal -offset indent
210 BSD:ls: ERROR: illegal option -- z
211 TO FIX: refer to manual BSD:ls:001
220 .Qq Li "text:severity:action:tag" ,
222 .Bd -literal -offset indent
223 illegal option -- z: ERROR
224 TO FIX: refer to manual BSD:ls:001
238 function first appeared in
245 argument makes little sense, since without an output specified,
247 is unable to do anything useful.
251 to output to the system console, the effective
252 user must have appropriate permission to write to
254 This means that on most systems
258 unless the effective user is root.