224 lines
6.6 KiB
Groff
224 lines
6.6 KiB
Groff
.\" $NetBSD: fmtmsg.3,v 1.3 2002/02/07 07:00:11 ross Exp $
|
|
.\"
|
|
.\" Copyright (c) 1999 The NetBSD Foundation, Inc.
|
|
.\" All rights reserved.
|
|
.\"
|
|
.\" This code is derived from software contributed to The NetBSD Foundation
|
|
.\" by Klaus Klein.
|
|
.\"
|
|
.\" 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.
|
|
.\" 3. All advertising materials mentioning features or use of this software
|
|
.\" must display the following acknowledgement:
|
|
.\" This product includes software developed by the NetBSD
|
|
.\" Foundation, Inc. and its contributors.
|
|
.\" 4. Neither the name of The NetBSD Foundation nor the names of its
|
|
.\" contributors may be used to endorse or promote products derived
|
|
.\" from this software without specific prior written permission.
|
|
.\"
|
|
.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. 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 FOUNDATION 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.
|
|
.\"
|
|
.Dd September 10, 1999
|
|
.Dt FMTMSG 3
|
|
.Os
|
|
.Sh NAME
|
|
.Nm fmtmsg
|
|
.Nd format and display a message
|
|
.Sh LIBRARY
|
|
.Lb libc
|
|
.Sh SYNOPSIS
|
|
.Fd #include \*[Lt]fmtmsg.h\*[Gt]
|
|
.Ft int
|
|
.Fn fmtmsg "long classification" "const char *label" "int severity" "const char *text" "const char *action" "const char *tag"
|
|
.Sh DESCRIPTION
|
|
The
|
|
.Fn fmtmsg
|
|
function can be used to display messages in the specified format.
|
|
Messages may be written either to standard error, to the console, or both.
|
|
.Pp
|
|
A formatted message consists of up to five components specified in
|
|
.Fa label ,
|
|
.Fa severity ,
|
|
.Fa text ,
|
|
.Fa action
|
|
and
|
|
.Fa tag .
|
|
Further information such as the origin of the message, the recoverability
|
|
from the condition causing the message and where to display the message
|
|
is specified in
|
|
.Fa classification .
|
|
.Ss classification
|
|
The
|
|
.Fa classification
|
|
argument consists of a major classification and several sub-classifications.
|
|
It has no effect on the content of the message displayed.
|
|
With the exception of the display sub-classification, only a single identifier
|
|
may be specified for each (sub-)classification. The following classifications
|
|
are available:
|
|
.Bl -tag -width MessageXSourceXSub-classificationsXX
|
|
.It Major Classifications
|
|
The source of the condition. Available identifiers are:
|
|
.Dv MM_HARD
|
|
(hardware),
|
|
.Dv MM_SOFT
|
|
(software), and
|
|
.Dv MM_FIRM
|
|
(firmware).
|
|
.It Message Source Sub-classifications
|
|
The type of software detecting the condition. Available identifiers are:
|
|
.Dv MM_APPL
|
|
(application),
|
|
.Dv MM_UTIL
|
|
(utility), and
|
|
.Dv MM_OPSYS
|
|
(operating system).
|
|
.It Display Sub-classifications
|
|
The displays the formatted messages is to be written to.
|
|
Available identifiers are:
|
|
.Dv MM_PRINT
|
|
(standard error stream) and
|
|
.Dv MM_CONSOLE
|
|
(system console).
|
|
.It Status Sub-classifications
|
|
The capability of the calling software to recover from the condition.
|
|
Available identifiers are:
|
|
.Dv MM_RECOVER
|
|
(recoverable) and
|
|
.Dv MM_NRECOV
|
|
(non-recoverable).
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Fa classification
|
|
is to be supplied,
|
|
.Dv MM_NULLMC
|
|
must be specified.
|
|
.Ss label
|
|
The
|
|
.Fa label
|
|
argument identifies the source of the message. It consists of two fields
|
|
separated by a colon (:). The first field is up to 10 characters, the second
|
|
is up to 14 characters.
|
|
.Pp
|
|
If no
|
|
.Fa label
|
|
is to be supplied,
|
|
.Dv MM_NULLLBL
|
|
must be specified.
|
|
.Ss severity
|
|
The seriousness of the condition causing the message.
|
|
The following
|
|
.Fa severity
|
|
levels are available:
|
|
.Bl -tag -width MM_WARNINGXX
|
|
.It Dv MM_HALT
|
|
The software has encountered a severe fault and is halting.
|
|
.It Dv MM_ERROR
|
|
The software has encountered a fault.
|
|
.It Dv MM_WARNING
|
|
The software has encountered an unusual non-fault condition.
|
|
.It Dv MM_INFO
|
|
The software informs about a non-error condition.
|
|
.El
|
|
.Pp
|
|
If no
|
|
.Fa severity
|
|
level is to be supplied,
|
|
.Dv MM_NOSEV
|
|
must be specified.
|
|
.Ss text
|
|
The description of the condition the software encountered. The character
|
|
string is not limited to a specific size.
|
|
.Pp
|
|
If no
|
|
.Fa text
|
|
is to be supplied,
|
|
.Dv MM_NOTXT
|
|
must be specified.
|
|
.Ss action
|
|
The first step to be taken to recover from the condition the software
|
|
encountered; it will be preceded by the prefix
|
|
.Dq TO FIX: .
|
|
The character string is not limited to a specific size.
|
|
.Pp
|
|
If no
|
|
.Fa action
|
|
is to be supplied,
|
|
.Dv MM_NOACT
|
|
must be specified.
|
|
.Ss tag
|
|
The on-line documentation which provides further information about the
|
|
condition and the message, such as
|
|
.Dq Xr fmtmsg 3 .
|
|
The character string is not limited to a specific size.
|
|
.Pp
|
|
If no
|
|
.Fa tag
|
|
is to be supplied,
|
|
.Dv MM_NOTAG
|
|
must be specified.
|
|
.Pp
|
|
Further effect on the formatting of the message as displayed on the
|
|
standard error stream (but not on the system console!) may be taken by
|
|
setting the
|
|
.Ev MSGVERB
|
|
environment variable, which selects the subset of message components
|
|
to be printed. It consists of a colon-separated list of the optional
|
|
keywords
|
|
.Fa label ,
|
|
.Fa severity ,
|
|
.Fa text ,
|
|
.Fa action ,
|
|
and
|
|
.Fa tag ,
|
|
which correspond to the arguments to
|
|
.Fn fmtmsg
|
|
with the same names.
|
|
If
|
|
.Ev MSGVERB
|
|
is either not set or malformed (containing empty or unknown keywords),
|
|
its content is ignored an all message components will be selected.
|
|
.Pp
|
|
Note that displaying a message on the system console may fail due to
|
|
inappropriate privileges or a non-permissive file mode of the console device.
|
|
.Sh RETURN VALUES
|
|
The
|
|
.Fn fmtmsg
|
|
function returns one of the following values:
|
|
.Bl -tag -width MM_NOTOKXXX
|
|
.It Dv MM_OK
|
|
The function succeeded.
|
|
.It Dv MM_NOTOK
|
|
The function failed completely.
|
|
.It Dv MM_NOMSG
|
|
The function was unable to generate a message on standard error,
|
|
but otherwise succeeded.
|
|
.It Dv MM_NOCOM
|
|
The function was unable to generate a message on the console,
|
|
but otherwise succeeded.
|
|
.El
|
|
.Sh SEE ALSO
|
|
.Xr printf 3 ,
|
|
.Xr syslog 3
|
|
.Sh STANDARDS
|
|
The
|
|
.Fn fmtmsg
|
|
function conforms to
|
|
.St -xsh5 .
|