1.\" $NetBSD: fmtmsg.3,v 1.4 2002/10/01 16:48:34 wiz Exp $ 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 46.Fd #include \*[Lt]fmtmsg.h\*[Gt] 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 50The 51.Fn fmtmsg 52function can be used to display messages in the specified format. 53Messages may be written either to standard error, to the console, or both. 54.Pp 55A formatted message consists of up to five components specified in 56.Fa label , 57.Fa severity , 58.Fa text , 59.Fa action 60and 61.Fa tag . 62Further information such as the origin of the message, the recoverability 63from the condition causing the message and where to display the message 64is specified in 65.Fa classification . 66.Ss classification 67The 68.Fa classification 69argument consists of a major classification and several sub-classifications. 70It has no effect on the content of the message displayed. 71With the exception of the display sub-classification, only a single identifier 72may be specified for each (sub-)classification. 73The following classifications 74are available: 75.Bl -tag -width MessageXSourceXSub-classificationsXX 76.It Major Classifications 77The source of the condition. 78Available identifiers are: 79.Dv MM_HARD 80(hardware), 81.Dv MM_SOFT 82(software), and 83.Dv MM_FIRM 84(firmware). 85.It Message Source Sub-classifications 86The type of software detecting the condition. 87Available identifiers are: 88.Dv MM_APPL 89(application), 90.Dv MM_UTIL 91(utility), and 92.Dv MM_OPSYS 93(operating system). 94.It Display Sub-classifications 95The displays the formatted messages is to be written to. 96Available identifiers are: 97.Dv MM_PRINT 98(standard error stream) and 99.Dv MM_CONSOLE 100(system console). 101.It Status Sub-classifications 102The capability of the calling software to recover from the condition. 103Available identifiers are: 104.Dv MM_RECOVER 105(recoverable) and 106.Dv MM_NRECOV 107(non-recoverable). 108.El 109.Pp 110If no 111.Fa classification 112is to be supplied, 113.Dv MM_NULLMC 114must be specified. 115.Ss label 116The 117.Fa label 118argument identifies the source of the message. 119It consists of two fields separated by a colon (:). 120The first field is up to 10 characters, the second is up to 14 characters. 121.Pp 122If no 123.Fa label 124is to be supplied, 125.Dv MM_NULLLBL 126must be specified. 127.Ss severity 128The seriousness of the condition causing the message. 129The following 130.Fa severity 131levels are available: 132.Bl -tag -width MM_WARNINGXX 133.It Dv MM_HALT 134The software has encountered a severe fault and is halting. 135.It Dv MM_ERROR 136The software has encountered a fault. 137.It Dv MM_WARNING 138The software has encountered an unusual non-fault condition. 139.It Dv MM_INFO 140The software informs about a non-error condition. 141.El 142.Pp 143If no 144.Fa severity 145level is to be supplied, 146.Dv MM_NOSEV 147must be specified. 148.Ss text 149The description of the condition the software encountered. 150The character 151string is not limited to a specific size. 152.Pp 153If no 154.Fa text 155is to be supplied, 156.Dv MM_NOTXT 157must be specified. 158.Ss action 159The first step to be taken to recover from the condition the software 160encountered; it will be preceded by the prefix 161.Dq TO FIX: . 162The character string is not limited to a specific size. 163.Pp 164If no 165.Fa action 166is to be supplied, 167.Dv MM_NOACT 168must be specified. 169.Ss tag 170The on-line documentation which provides further information about the 171condition and the message, such as 172.Dq Xr fmtmsg 3 . 173The character string is not limited to a specific size. 174.Pp 175If no 176.Fa tag 177is to be supplied, 178.Dv MM_NOTAG 179must be specified. 180.Pp 181Further effect on the formatting of the message as displayed on the 182standard error stream (but not on the system console!) may be taken by 183setting the 184.Ev MSGVERB 185environment variable, which selects the subset of message components 186to be printed. 187It consists of a colon-separated list of the optional keywords 188.Fa label , 189.Fa severity , 190.Fa text , 191.Fa action , 192and 193.Fa tag , 194which correspond to the arguments to 195.Fn fmtmsg 196with the same names. 197If 198.Ev MSGVERB 199is either not set or malformed (containing empty or unknown keywords), 200its content is ignored an all message components will be selected. 201.Pp 202Note that displaying a message on the system console may fail due to 203inappropriate privileges or a non-permissive file mode of the console device. 204.Sh RETURN VALUES 205The 206.Fn fmtmsg 207function returns one of the following values: 208.Bl -tag -width MM_NOTOKXXX 209.It Dv MM_OK 210The function succeeded. 211.It Dv MM_NOTOK 212The function failed completely. 213.It Dv MM_NOMSG 214The function was unable to generate a message on standard error, 215but otherwise succeeded. 216.It Dv MM_NOCOM 217The function was unable to generate a message on the console, 218but otherwise succeeded. 219.El 220.Sh SEE ALSO 221.Xr printf 3 , 222.Xr syslog 3 223.Sh STANDARDS 224The 225.Fn fmtmsg 226function conforms to 227.St -xsh5 . 228