2fe8fb192f
There is important information about booting non-ack images in docs/UPDATING. ack/aout-format images can't be built any more, and booting clang/ELF-format ones is a little different. Updating to the new boot monitor is recommended. Changes in this commit: . drop boot monitor -> allowing dropping ack support . facility to copy ELF boot files to /boot so that old boot monitor can still boot fairly easily, see UPDATING . no more ack-format libraries -> single-case libraries . some cleanup of OBJECT_FMT, COMPILER_TYPE, etc cases . drop several ack toolchain commands, but not all support commands (e.g. aal is gone but acksize is not yet). . a few libc files moved to netbsd libc dir . new /bin/date as minix date used code in libc/ . test compile fix . harmonize includes . /usr/lib is no longer special: without ack, /usr/lib plays no kind of special bootstrapping role any more and bootstrapping is done exclusively through packages, so releases depend even less on the state of the machine making them now. . rename nbsd_lib* to lib* . reduce mtree
220 lines
6.2 KiB
Groff
220 lines
6.2 KiB
Groff
.\" $NetBSD: fmtmsg.3,v 1.6 2008/04/30 13:10:50 martin 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.
|
|
.\"
|
|
.\" 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
|
|
.In fmtmsg.h
|
|
.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 .
|