Annotation of src/lib/libc/gen/fmtmsg.3, Revision 1.1.10.2
1.1.10.2! nathanw 1: .\" $NetBSD: fmtmsg.3,v 1.1.10.1 2001/10/08 20:18:50 nathanw Exp $
1.1 kleink 2: .\"
3: .\" Copyright (c) 1999 The NetBSD Foundation, Inc.
4: .\" All rights reserved.
5: .\"
6: .\" This code is derived from software contributed to The NetBSD Foundation
7: .\" by Klaus Klein.
8: .\"
9: .\" Redistribution and use in source and binary forms, with or without
10: .\" modification, are permitted provided that the following conditions
11: .\" are met:
12: .\" 1. Redistributions of source code must retain the above copyright
13: .\" notice, this list of conditions and the following disclaimer.
14: .\" 2. Redistributions in binary form must reproduce the above copyright
15: .\" notice, this list of conditions and the following disclaimer in the
16: .\" documentation and/or other materials provided with the distribution.
17: .\" 3. All advertising materials mentioning features or use of this software
18: .\" must display the following acknowledgement:
19: .\" This product includes software developed by the NetBSD
20: .\" Foundation, Inc. and its contributors.
21: .\" 4. Neither the name of The NetBSD Foundation nor the names of its
22: .\" contributors may be used to endorse or promote products derived
23: .\" from this software without specific prior written permission.
24: .\"
25: .\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS
26: .\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
27: .\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
28: .\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS
29: .\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
30: .\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
31: .\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
32: .\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
33: .\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
34: .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
35: .\" POSSIBILITY OF SUCH DAMAGE.
36: .\"
37: .Dd September 10, 1999
38: .Dt FMTMSG 3
39: .Os
40: .Sh NAME
41: .Nm fmtmsg
42: .Nd format and display a message
43: .Sh LIBRARY
44: .Lb libc
45: .Sh SYNOPSIS
1.1.10.2! nathanw 46: .Fd #include \*[Lt]fmtmsg.h\*[Gt]
1.1 kleink 47: .Ft int
48: .Fn fmtmsg "long classification" "const char *label" "int severity" "const char *text" "const char *action" "const char *tag"
49: .Sh DESCRIPTION
50: The
51: .Fn fmtmsg
52: function can be used to display messages in the specified format.
53: Messages may be written either to standard error, to the console, or both.
54: .Pp
55: A formatted message consists of up to five components specified in
56: .Fa label ,
57: .Fa severity ,
58: .Fa text ,
59: .Fa action
60: and
61: .Fa tag .
62: Further information such as the origin of the message, the recoverability
63: from the condition causing the message and where to display the message
64: is specified in
1.1.10.1 nathanw 65: .Fa classification .
1.1 kleink 66: .Ss classification
67: The
68: .Fa classification
69: argument consists of a major classification and several sub-classifications.
70: It has no effect on the content of the message displayed.
71: With the exception of the display sub-classification, only a single identifier
72: may be specified for each (sub-)classification. The following classifications
73: are available:
74: .Bl -tag -width MessageXSourceXSub-classificationsXX
75: .It Major Classifications
76: The source of the condition. Available identifiers are:
77: .Dv MM_HARD
78: (hardware),
79: .Dv MM_SOFT
80: (software), and
81: .Dv MM_FIRM
82: (firmware).
83: .It Message Source Sub-classifications
84: The type of software detecting the condition. Available identifiers are:
85: .Dv MM_APPL
86: (application),
87: .Dv MM_UTIL
88: (utility), and
89: .Dv MM_OPSYS
90: (operating system).
91: .It Display Sub-classifications
92: The displays the formatted messages is to be written to.
93: Available identifiers are:
94: .Dv MM_PRINT
95: (standard error stream) and
96: .Dv MM_CONSOLE
97: (system console).
98: .It Status Sub-classifications
99: The capability of the calling software to recover from the condition.
100: Available identifiers are:
101: .Dv MM_RECOVER
102: (recoverable) and
103: .Dv MM_NRECOV
104: (non-recoverable).
105: .El
106: .Pp
107: If no
108: .Fa classification
109: is to be supplied,
110: .Dv MM_NULLMC
111: must be specified.
112: .Ss label
113: The
114: .Fa label
115: argument identifies the source of the message. It consists of two fields
116: separated by a colon (:). The first field is up to 10 characters, the second
117: is up to 14 characters.
118: .Pp
119: If no
120: .Fa label
121: is to be supplied,
122: .Dv MM_NULLLBL
123: must be specified.
124: .Ss severity
125: The seriousness of the condition causing the message.
126: The following
127: .Fa severity
128: levels are available:
129: .Bl -tag -width MM_WARNINGXX
130: .It Dv MM_HALT
131: The software has encountered a severe fault and is halting.
132: .It Dv MM_ERROR
133: The software has encountered a fault.
134: .It Dv MM_WARNING
135: The software has encountered an unusual non-fault condition.
136: .It Dv MM_INFO
137: The software informs about a non-error condition.
138: .El
139: .Pp
140: If no
141: .Fa severity
142: level is to be supplied,
143: .Dv MM_NOSEV
144: must be specified.
145: .Ss text
146: The description of the condition the software encountered. The character
147: string is not limited to a specific size.
148: .Pp
149: If no
150: .Fa text
151: is to be supplied,
152: .Dv MM_NOTXT
153: must be specified.
154: .Ss action
155: The first step to be taken to recover from the condition the software
156: encountered; it will be preceded by the prefix
157: .Dq TO FIX: .
158: The character string is not limited to a specific size.
159: .Pp
160: If no
161: .Fa action
162: is to be supplied,
163: .Dv MM_NOACT
164: must be specified.
165: .Ss tag
166: The on-line documentation which provides further information about the
167: condition and the message, such as
168: .Dq Xr fmtmsg 3 .
169: The character string is not limited to a specific size.
170: .Pp
171: If no
172: .Fa tag
173: is to be supplied,
174: .Dv MM_NOTAG
175: must be specified.
176: .Pp
177: Further effect on the formatting of the message as displayed on the
178: standard error stream (but not on the system console!) may be taken by
179: setting the
180: .Ev MSGVERB
181: environment variable, which selects the subset of message components
182: to be printed. It consists of a colon-separated list of the optional
183: keywords
184: .Fa label ,
185: .Fa severity ,
186: .Fa text ,
187: .Fa action ,
188: and
189: .Fa tag ,
190: which correspond to the arguments to
191: .Fn fmtmsg
192: with the same names.
193: If
194: .Ev MSGVERB
195: is either not set or malformed (containing empty or unknown keywords),
196: its content is ignored an all message components will be selected.
197: .Pp
198: Note that displaying a message on the system console may fail due to
199: inappropriate privileges or a non-permissive file mode of the console device.
1.1.10.1 nathanw 200: .Sh RETURN VALUES
1.1 kleink 201: The
202: .Fn fmtmsg
203: function returns one of the following values:
204: .Bl -tag -width MM_NOTOKXXX
205: .It Dv MM_OK
206: The function succeeded.
207: .It Dv MM_NOTOK
208: The function failed completely.
209: .It Dv MM_NOMSG
210: The function was unable to generate a message on standard error,
211: but otherwise succeeded.
212: .It Dv MM_NOCOM
213: The function was unable to generate a message on the console,
214: but otherwise succeeded.
215: .El
216: .Sh SEE ALSO
217: .Xr printf 3 ,
218: .Xr syslog 3
219: .Sh STANDARDS
220: The
221: .Fn fmtmsg
222: function conforms to
223: .St -xsh5 .
CVSweb <webmaster@jp.NetBSD.org>