[apple/libc.git] / gen / FreeBSD / fmtmsg.3

.\"
.\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org>
.\" All rights reserved.
.\"
.\" Redistribution and use in source and binary forms, with or without
.\" modification, are permitted provided that the following conditions
.\" are met:
.\" 1. Redistributions of source code must retain the above copyright
.\"    notice, this list of conditions and the following disclaimer.
.\" 2. Redistributions in binary form must reproduce the above copyright
.\"    notice, this list of conditions and the following disclaimer in the
.\"    documentation and/or other materials provided with the distribution.
.\"
.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
.\" ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
.\" SUCH DAMAGE.
.\"
.\" $FreeBSD: src/lib/libc/gen/fmtmsg.3,v 1.4 2002/12/04 18:57:44 ru Exp $
.\"
.Dd August 5, 2002
.Dt FMTMSG 3
.Os
.Sh NAME
.Nm fmtmsg
.Nd display a detailed diagnostic message
.Sh LIBRARY
.Lb libc
.Sh SYNOPSIS
.In fmtmsg.h
.Ft int
.Fo fmtmsg
.Fa "long classification" "const char *label" "int severity"
.Fa "const char *text" "const char *action" "const char *tag"
.Fc
.Sh DESCRIPTION
The
.Fn fmtmsg
function displays a detailed diagnostic message, based on
the supplied arguments, to
.Dv stderr
and/or the system console.
.Pp
The
.Fa classification
argument is the bitwise inclusive
.Tn OR
of zero or one of the manifest constants from
each of the classification groups below.
The Output classification group is an exception since both
.Dv MM_PRINT
and
.Dv MM_CONSOLE
may be specified.
.Bl -tag -width indent
.It Output
.Bl -tag -width ".Dv MM_CONSOLE"
.It Dv MM_PRINT
Output should take place on
.Dv stderr .
.It Dv MM_CONSOLE
Output should take place on the system console.
.El
.It "Source of Condition (Major)"
.Bl -tag -width ".Dv MM_CONSOLE"
.It Dv MM_HARD
The source of the condition is hardware related.
.It Dv MM_SOFT
The source of the condition is software related.
.It Dv MM_FIRM
The source of the condition is firmware related.
.El
.It "Source of Condition (Minor)"
.Bl -tag -width ".Dv MM_CONSOLE"
.It Dv MM_APPL
The condition was detected at the application level.
.It Dv MM_UTIL
The condition was detected at the utility level.
.It Dv MM_OPSYS
The condition was detected at the operating system level.
.El
.It Status
.Bl -tag -width ".Dv MM_CONSOLE"
.It Dv MM_RECOVER
The application can recover from the condition.
.It Dv MM_NRECOV
The application is unable to recover from the condition.
.El
.El
.Pp
Alternatively, the
.Dv MM_NULLMC
manifest constant may be used to specify no classification.
.Pp
The
.Fa label
argument indicates the source of the message.
It is made up of two fields separated by a colon
.Pq Ql \&: .
The first field can be up to 10 bytes,
and the second field can be up to 14 bytes.
The
.Dv MM_NULLLBL
manifest constant may be used to specify no label.
.Pp
The
.Fa severity
argument identifies the importance of the condition.
One of the following manifest constants should be used for this argument.
.Bl -tag -offset indent -width ".Dv MM_WARNING"
.It Dv MM_HALT
The application has confronted a serious fault and is halting.
.It Dv MM_ERROR
The application has detected a fault.
.It Dv MM_WARNING
The application has detected an unusual condition,
that could be indicative of a problem.
.It Dv MM_INFO
The application is providing information about a non-error condition.
.It Dv MM_NOSEV
No severity level supplied.
.El
.Pp
The
.Fa text
argument details the error condition that caused the message.
There is no limit on the size of this character string.
The
.Dv MM_NULLTXT
manifest constant may be used to specify no text.
.Pp
The
.Fa action
argument details how the error-recovery process should begin.
Upon output,
.Fn fmtmsg
will prefix
.Qq Li "TO FIX:"
to the beginning of the
.Fa action
argument.
The
.Dv MM_NULLACT
manifest constant may be used to specify no action.
.Pp
The
.Fa tag
argument should reference online documentation for the message.
This usually includes the
.Fa label
and a unique identifying number.
An example tag is
.Qq Li BSD:ls:168 .
The
.Dv MM_NULLTAG
manifest constant may be used to specify no tag.
.Sh RETURN VALUES
The
.Fn fmtmsg
function returns
.Dv MM_OK
upon success,
.Dv MM_NOMSG
to indicate output to
.Dv stderr
failed,
.Dv MM_NOCON
to indicate output to the system console failed, or
.Dv MM_NOTOK
to indicate output to
.Dv stderr
and the system console failed.
.Sh ENVIRONMENT
The
.Ev MSGVERB
(message verbosity)
environment variable specifies which arguments to
.Fn fmtmsg
will be output to
.Dv stderr ,
and in which order.
.Ev MSGVERB
should be a colon
.Pq Ql \&:
separated list of identifiers.
Valid identifiers include:
.Li label , severity , text , action ,
and
.Li tag .
If invalid identifiers are specified or incorrectly separated,
the default message verbosity and ordering will be used.
The default ordering is equivalent to a
.Ev MSGVERB
with a value of
.Qq Li label:severity:text:action:tag .
.Sh EXAMPLES
The code:
.Bd -literal -offset indent
fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR,
    "illegal option -- z", "refer to manual", "BSD:ls:001");
.Ed
.Pp
will output:
.Bd -literal -offset indent
BSD:ls: ERROR: illegal option -- z
TO FIX: refer to manual BSD:ls:001
.Ed
.Pp
to
.Dv stderr .
.Pp
The same code, with
.Ev MSGVERB
set to
.Qq Li "text:severity:action:tag" ,
produces:
.Bd -literal -offset indent
illegal option -- z: ERROR
TO FIX: refer to manual BSD:ls:001
.Ed
.Sh SEE ALSO
.Xr err 3 ,
.Xr exit 3 ,
.Xr strerror 3
.Sh STANDARDS
The
.Fn fmtmsg
function conforms to
.St -p1003.1-2001 .
.Sh HISTORY
The
.Fn fmtmsg
function first appeared in
.Fx 5.0 .
.Sh BUGS
Specifying
.Dv MM_NULLMC
for the
.Fa classification
argument makes little sense, since without an output specified,
.Fn fmtmsg
is unable to do anything useful.
.Pp
In order for
.Fn fmtmsg
to output to the system console, the effective
user must have appropriate permission to write to
.Pa /dev/console .
This means that on most systems
.Fn fmtmsg
will return
.Dv MM_NOCON
unless the effective user is root.
Commit	Line	Data
59e0d9fe A	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.