1.\" $NetBSD: fmtmsg.3,v 1.7 2011/04/11 05:59:11 jruoho 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.\" 18.\" THIS SOFTWARE IS PROVIDED BY THE NETBSD FOUNDATION, INC. AND CONTRIBUTORS 19.\" ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED 20.\" TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 21.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE FOUNDATION OR CONTRIBUTORS 22.\" BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR 23.\" CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF 24.\" SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS 25.\" INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN 26.\" CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 27.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE 28.\" POSSIBILITY OF SUCH DAMAGE. 29.\" 30.Dd April 11, 2011 31.Dt FMTMSG 3 32.Os 33.Sh NAME 34.Nm fmtmsg 35.Nd format and display a message 36.Sh LIBRARY 37.Lb libc 38.Sh SYNOPSIS 39.In fmtmsg.h 40.Ft int 41.Fn fmtmsg "long classification" "const char *label" "int severity" "const char *text" "const char *action" "const char *tag" 42.Sh DESCRIPTION 43The 44.Fn fmtmsg 45function can be used to display messages in the specified format. 46Messages may be written either to standard error, to the console, or both. 47.Pp 48A formatted message consists of up to five components specified in 49.Fa label , 50.Fa severity , 51.Fa text , 52.Fa action 53and 54.Fa tag . 55Further information such as the origin of the message, the recoverability 56from the condition causing the message and where to display the message 57is specified in 58.Fa classification . 59.Ss Classification 60The 61.Fa classification 62argument consists of a major classification and several sub-classifications. 63It has no effect on the content of the message displayed. 64With the exception of the display sub-classification, only a single identifier 65may be specified for each (sub-)classification. 66The following classifications 67are available: 68.Bl -tag -width "XXX" 69.It Em Major classifications 70The source of the condition. 71Available identifiers are: 72.Dv MM_HARD 73(hardware), 74.Dv MM_SOFT 75(software), and 76.Dv MM_FIRM 77(firmware). 78.It Em Message source sub-classifications 79The type of software detecting the condition. 80Available identifiers are: 81.Dv MM_APPL 82(application), 83.Dv MM_UTIL 84(utility), and 85.Dv MM_OPSYS 86(operating system). 87.It Em Display sub-classifications 88The displays the formatted messages is to be written to. 89Available identifiers are: 90.Dv MM_PRINT 91(standard error stream) and 92.Dv MM_CONSOLE 93(system console). 94.It Em Status sub-classifications 95The capability of the calling software to recover from the condition. 96Available identifiers are: 97.Dv MM_RECOVER 98(recoverable) and 99.Dv MM_NRECOV 100(non-recoverable). 101.El 102.Pp 103If no 104.Fa classification 105is to be supplied, 106.Dv MM_NULLMC 107must be specified. 108.Ss Label 109The 110.Fa label 111argument identifies the source of the message. 112It consists of two fields separated by a colon (:). 113The first field is up to 10 characters, the second is up to 14 characters. 114.Pp 115If no 116.Fa label 117is to be supplied, 118.Dv MM_NULLLBL 119must be specified. 120.Ss Severity 121The seriousness of the condition causing the message. 122The following 123.Fa severity 124levels are available: 125.Bl -tag -width MM_WARNING -offset indent 126.It Dv MM_HALT 127The software has encountered a severe fault and is halting. 128.It Dv MM_ERROR 129The software has encountered a fault. 130.It Dv MM_WARNING 131The software has encountered an unusual non-fault condition. 132.It Dv MM_INFO 133The software informs about a non-error condition. 134.El 135.Pp 136If no 137.Fa severity 138level is to be supplied, 139.Dv MM_NOSEV 140must be specified. 141.Ss Text 142The description of the condition the software encountered. 143The character 144string is not limited to a specific size. 145.Pp 146If no 147.Fa text 148is to be supplied, 149.Dv MM_NOTXT 150must be specified. 151.Ss Action 152The first step to be taken to recover from the condition the software 153encountered; it will be preceded by the prefix 154.Dq TO FIX: . 155The character string is not limited to a specific size. 156.Pp 157If no 158.Fa action 159is to be supplied, 160.Dv MM_NOACT 161must be specified. 162.Ss Tag 163The on-line documentation which provides further information about the 164condition and the message, such as 165.Dq Xr fmtmsg 3 . 166The character string is not limited to a specific size. 167.Pp 168If no 169.Fa tag 170is to be supplied, 171.Dv MM_NOTAG 172must be specified. 173.Pp 174Further effect on the formatting of the message as displayed on the 175standard error stream (but not on the system console!) may be taken by 176setting the 177.Ev MSGVERB 178environment variable, which selects the subset of message components 179to be printed. 180It consists of a colon-separated list of the optional keywords 181.Fa label , 182.Fa severity , 183.Fa text , 184.Fa action , 185and 186.Fa tag , 187which correspond to the arguments to 188.Fn fmtmsg 189with the same names. 190If 191.Ev MSGVERB 192is either not set or malformed (containing empty or unknown keywords), 193its content is ignored an all message components will be selected. 194.Pp 195Note that displaying a message on the system console may fail due to 196inappropriate privileges or a non-permissive file mode of the console device. 197.Sh RETURN VALUES 198The 199.Fn fmtmsg 200function returns one of the following values: 201.Bl -tag -width MM_NOTOKXXX 202.It Dv MM_OK 203The function succeeded. 204.It Dv MM_NOTOK 205The function failed completely. 206.It Dv MM_NOMSG 207The function was unable to generate a message on standard error, 208but otherwise succeeded. 209.It Dv MM_NOCOM 210The function was unable to generate a message on the console, 211but otherwise succeeded. 212.El 213.Sh SEE ALSO 214.Xr printf 3 , 215.Xr syslog 3 216.Sh STANDARDS 217The 218.Fn fmtmsg 219function conforms to 220.St -xsh5 . 221