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