1.\" 2.\" Copyright (c) 2002 Mike Barcroft <mike@FreeBSD.org> 3.\" All rights reserved. 4.\" 5.\" Redistribution and use in source and binary forms, with or without 6.\" modification, are permitted provided that the following conditions 7.\" are met: 8.\" 1. Redistributions of source code must retain the above copyright 9.\" notice, this list of conditions and the following disclaimer. 10.\" 2. Redistributions in binary form must reproduce the above copyright 11.\" notice, this list of conditions and the following disclaimer in the 12.\" documentation and/or other materials provided with the distribution. 13.\" 14.\" THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND 15.\" ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 16.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE 17.\" ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE 18.\" FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL 19.\" DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS 20.\" OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 21.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT 22.\" LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY 23.\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF 24.\" SUCH DAMAGE. 25.\" 26.\" $FreeBSD$ 27.\" 28.Dd August 5, 2002 29.Dt FMTMSG 3 30.Os 31.Sh NAME 32.Nm fmtmsg 33.Nd display a detailed diagnostic message 34.Sh LIBRARY 35.Lb libc 36.Sh SYNOPSIS 37.In fmtmsg.h 38.Ft int 39.Fo fmtmsg 40.Fa "long classification" "const char *label" "int severity" 41.Fa "const char *text" "const char *action" "const char *tag" 42.Fc 43.Sh DESCRIPTION 44The 45.Fn fmtmsg 46function displays a detailed diagnostic message, based on 47the supplied arguments, to 48.Dv stderr 49and/or the system console. 50.Pp 51The 52.Fa classification 53argument is the bitwise inclusive 54.Tn OR 55of zero or one of the manifest constants from 56each of the classification groups below. 57The Output classification group is an exception since both 58.Dv MM_PRINT 59and 60.Dv MM_CONSOLE 61may be specified. 62.Bl -tag -width indent 63.It Output 64.Bl -tag -width ".Dv MM_CONSOLE" 65.It Dv MM_PRINT 66Output should take place on 67.Dv stderr . 68.It Dv MM_CONSOLE 69Output should take place on the system console. 70.El 71.It "Source of Condition (Major)" 72.Bl -tag -width ".Dv MM_CONSOLE" 73.It Dv MM_HARD 74The source of the condition is hardware related. 75.It Dv MM_SOFT 76The source of the condition is software related. 77.It Dv MM_FIRM 78The source of the condition is firmware related. 79.El 80.It "Source of Condition (Minor)" 81.Bl -tag -width ".Dv MM_CONSOLE" 82.It Dv MM_APPL 83The condition was detected at the application level. 84.It Dv MM_UTIL 85The condition was detected at the utility level. 86.It Dv MM_OPSYS 87The condition was detected at the operating system level. 88.El 89.It Status 90.Bl -tag -width ".Dv MM_CONSOLE" 91.It Dv MM_RECOVER 92The application can recover from the condition. 93.It Dv MM_NRECOV 94The application is unable to recover from the condition. 95.El 96.El 97.Pp 98Alternatively, the 99.Dv MM_NULLMC 100manifest constant may be used to specify no classification. 101.Pp 102The 103.Fa label 104argument indicates the source of the message. 105It is made up of two fields separated by a colon 106.Pq Ql \&: . 107The first field can be up to 10 bytes, 108and the second field can be up to 14 bytes. 109The 110.Dv MM_NULLLBL 111manifest constant may be used to specify no label. 112.Pp 113The 114.Fa severity 115argument identifies the importance of the condition. 116One of the following manifest constants should be used for this argument. 117.Bl -tag -offset indent -width ".Dv MM_WARNING" 118.It Dv MM_HALT 119The application has confronted a serious fault and is halting. 120.It Dv MM_ERROR 121The application has detected a fault. 122.It Dv MM_WARNING 123The application has detected an unusual condition, 124that could be indicative of a problem. 125.It Dv MM_INFO 126The application is providing information about a non-error condition. 127.It Dv MM_NOSEV 128No severity level supplied. 129.El 130.Pp 131The 132.Fa text 133argument details the error condition that caused the message. 134There is no limit on the size of this character string. 135The 136.Dv MM_NULLTXT 137manifest constant may be used to specify no text. 138.Pp 139The 140.Fa action 141argument details how the error-recovery process should begin. 142Upon output, 143.Fn fmtmsg 144will prefix 145.Qq Li "TO FIX:" 146to the beginning of the 147.Fa action 148argument. 149The 150.Dv MM_NULLACT 151manifest constant may be used to specify no action. 152.Pp 153The 154.Fa tag 155argument should reference online documentation for the message. 156This usually includes the 157.Fa label 158and a unique identifying number. 159An example tag is 160.Qq Li BSD:ls:168 . 161The 162.Dv MM_NULLTAG 163manifest constant may be used to specify no tag. 164.Sh RETURN VALUES 165The 166.Fn fmtmsg 167function returns 168.Dv MM_OK 169upon success, 170.Dv MM_NOMSG 171to indicate output to 172.Dv stderr 173failed, 174.Dv MM_NOCON 175to indicate output to the system console failed, or 176.Dv MM_NOTOK 177to indicate output to 178.Dv stderr 179and the system console failed. 180.Sh ENVIRONMENT 181The 182.Ev MSGVERB 183(message verbosity) 184environment variable specifies which arguments to 185.Fn fmtmsg 186will be output to 187.Dv stderr , 188and in which order. 189.Ev MSGVERB 190should be a colon 191.Pq Ql \&: 192separated list of identifiers. 193Valid identifiers include: 194.Li label , severity , text , action , 195and 196.Li tag . 197If invalid identifiers are specified or incorrectly separated, 198the default message verbosity and ordering will be used. 199The default ordering is equivalent to a 200.Ev MSGVERB 201with a value of 202.Qq Li label:severity:text:action:tag . 203.Sh EXAMPLES 204The code: 205.Bd -literal -offset indent 206fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls", MM_ERROR, 207 "illegal option -- z", "refer to manual", "BSD:ls:001"); 208.Ed 209.Pp 210will output: 211.Bd -literal -offset indent 212BSD:ls: ERROR: illegal option -- z 213TO FIX: refer to manual BSD:ls:001 214.Ed 215.Pp 216to 217.Dv stderr . 218.Pp 219The same code, with 220.Ev MSGVERB 221set to 222.Qq Li "text:severity:action:tag" , 223produces: 224.Bd -literal -offset indent 225illegal option -- z: ERROR 226TO FIX: refer to manual BSD:ls:001 227.Ed 228.Sh SEE ALSO 229.Xr err 3 , 230.Xr exit 3 , 231.Xr strerror 3 232.Sh STANDARDS 233The 234.Fn fmtmsg 235function conforms to 236.St -p1003.1-2001 . 237.Sh HISTORY 238The 239.Fn fmtmsg 240function first appeared in 241.Fx 5.0 . 242.Sh BUGS 243Specifying 244.Dv MM_NULLMC 245for the 246.Fa classification 247argument makes little sense, since without an output specified, 248.Fn fmtmsg 249is unable to do anything useful. 250.Pp 251In order for 252.Fn fmtmsg 253to output to the system console, the effective 254user must have appropriate permission to write to 255.Pa /dev/console . 256This means that on most systems 257.Fn fmtmsg 258will return 259.Dv MM_NOCON 260unless the effective user is root. 261