]> git.saurik.com Git - apple/libc.git/blob - gen/FreeBSD/fmtmsg.3
Libc-498.1.5.tar.gz
[apple/libc.git] / gen / FreeBSD / 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 .\"
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.