[BACK]Return to fmtmsg.3 CVS log [TXT][DIR] Up to [cvs.NetBSD.org] / src / lib / libc / gen

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>