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