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