1.\" $NetBSD: fmtmsg.3,v 1.3 2002/02/07 07:00:11 ross 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. The following classifications 73are available: 74.Bl -tag -width MessageXSourceXSub-classificationsXX 75.It Major Classifications 76The 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 84The 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 92The displays the formatted messages is to be written to. 93Available identifiers are: 94.Dv MM_PRINT 95(standard error stream) and 96.Dv MM_CONSOLE 97(system console). 98.It Status Sub-classifications 99The capability of the calling software to recover from the condition. 100Available identifiers are: 101.Dv MM_RECOVER 102(recoverable) and 103.Dv MM_NRECOV 104(non-recoverable). 105.El 106.Pp 107If no 108.Fa classification 109is to be supplied, 110.Dv MM_NULLMC 111must be specified. 112.Ss label 113The 114.Fa label 115argument identifies the source of the message. It consists of two fields 116separated by a colon (:). The first field is up to 10 characters, the second 117is up to 14 characters. 118.Pp 119If no 120.Fa label 121is to be supplied, 122.Dv MM_NULLLBL 123must be specified. 124.Ss severity 125The seriousness of the condition causing the message. 126The following 127.Fa severity 128levels are available: 129.Bl -tag -width MM_WARNINGXX 130.It Dv MM_HALT 131The software has encountered a severe fault and is halting. 132.It Dv MM_ERROR 133The software has encountered a fault. 134.It Dv MM_WARNING 135The software has encountered an unusual non-fault condition. 136.It Dv MM_INFO 137The software informs about a non-error condition. 138.El 139.Pp 140If no 141.Fa severity 142level is to be supplied, 143.Dv MM_NOSEV 144must be specified. 145.Ss text 146The description of the condition the software encountered. The character 147string is not limited to a specific size. 148.Pp 149If no 150.Fa text 151is to be supplied, 152.Dv MM_NOTXT 153must be specified. 154.Ss action 155The first step to be taken to recover from the condition the software 156encountered; it will be preceded by the prefix 157.Dq TO FIX: . 158The character string is not limited to a specific size. 159.Pp 160If no 161.Fa action 162is to be supplied, 163.Dv MM_NOACT 164must be specified. 165.Ss tag 166The on-line documentation which provides further information about the 167condition and the message, such as 168.Dq Xr fmtmsg 3 . 169The character string is not limited to a specific size. 170.Pp 171If no 172.Fa tag 173is to be supplied, 174.Dv MM_NOTAG 175must be specified. 176.Pp 177Further effect on the formatting of the message as displayed on the 178standard error stream (but not on the system console!) may be taken by 179setting the 180.Ev MSGVERB 181environment variable, which selects the subset of message components 182to be printed. It consists of a colon-separated list of the optional 183keywords 184.Fa label , 185.Fa severity , 186.Fa text , 187.Fa action , 188and 189.Fa tag , 190which correspond to the arguments to 191.Fn fmtmsg 192with the same names. 193If 194.Ev MSGVERB 195is either not set or malformed (containing empty or unknown keywords), 196its content is ignored an all message components will be selected. 197.Pp 198Note that displaying a message on the system console may fail due to 199inappropriate privileges or a non-permissive file mode of the console device. 200.Sh RETURN VALUES 201The 202.Fn fmtmsg 203function returns one of the following values: 204.Bl -tag -width MM_NOTOKXXX 205.It Dv MM_OK 206The function succeeded. 207.It Dv MM_NOTOK 208The function failed completely. 209.It Dv MM_NOMSG 210The function was unable to generate a message on standard error, 211but otherwise succeeded. 212.It Dv MM_NOCOM 213The function was unable to generate a message on the console, 214but otherwise succeeded. 215.El 216.Sh SEE ALSO 217.Xr printf 3 , 218.Xr syslog 3 219.Sh STANDARDS 220The 221.Fn fmtmsg 222function conforms to 223.St -xsh5 . 224