*** UNIX MANUAL PAGE BROWSER ***

fmtmsg(3) Library Functions Manual fmtmsg(3) NAME fmtmsg - Displays a message in the specified format LIBRARY Standard C Library (libc.so, libc.a) SYNOPSIS #include <fmtmsg.h> int fmtmsg( long classification, const char *label, int severity, const char *text, const char *action, const char *tag); STANDARDS Interfaces documented on this reference page conform to industry stan- dards as follows: fmtmsg(): XPG4-UNIX Refer to the standards(5) reference page for more information about in- dustry standards and associated tags. PARAMETERS Defines the source of the message and directs the display of the for- matted message, using the classes of identifiers listed below. Any one identifier from a subclass can be combined with a single identifier from a different subclass. Using two or more identifiers from the same subclass is not allowed, with the exception of identifiers from the Display subclass. (Both Display subclass identifiers may be used so that messages can be displayed to both standard error and the system console). The following identifiers are available: Identifies the source of the condition. The options are MM_HARD (hardware), MM_SOFT (software), and MM_FIRM (firmware). Identifies the software type that exhibits the problem. The options are MM_APPL (application), MM_UTIL (utility), MM_OPSYS, and (operating system). Identifies where the mes- sage is to be displayed. The options are MM_PRINT (standard error) or MM_CONSOLE (system console). One or both options may be used. Identi- fies whether the application will recover from the condition. The op- tions are MM_RECOVER (can recover) or MM_NRECOV (cannot recover). An additional identifier, MM_NULLMC, indicates that no classification component is supplied for the message. Identifies the message source. The label format consists of two fields separated by a colon. The first field can contain up to 10 bytes. The second field can contain up to 14 bytes. It is suggested that label contain at least the name of the application. Indicates the seriousness of the condition. The options are as follows: Indicates that application has encountered an error. Produces the string ERROR. Indicates that the application has stopped running because it has found a severe error. Produces the string HALT. Displays information about a nonerror condition. Produces the string INFO. Indicates that no severity level is provided for the message. Indicates a condition that might be a problem and should be monitored. Produces the string WARNING. Describes the error that pro- duced the message. The text string has no maximum length. If the text string is empty, the text produced is unspecified. Describes the first action to be taken to recover from the error condition. The fmtmsg() function precedes every action string with the prefix TO FIX:. The ac- tion string has no maximum length. Points the user to the online docu- mentation for the message. It is suggested that tag include the label as well as a unique identifying number. For example, program:subrou- tine:003. DESCRIPTION The fmtmsg() function writes a formatted message to either standard er- ror, the system console, or both. Any message typically written to standard error (stderr) by printf() can also be displayed using the fmtmsg() function. A formatted message consists of up to five components (label, severity, text, action, and tag), as described in the previous section. The classification component is not part of a message displayed to the user, but defines the source of the message and directs the display of the formatted message. To omit any field from messages, use the null value of the field's pa- rameter, as shown in the following table. tab(@); lfHB lfHB lfHB lfHB l l l l. _ Parameter@Type@Null Value@Identifier _ label@char*@(char*)NULL@MM_NULLLBL severity@int@0@MM_NULLSEV classifi- cation@long@0L@MM_NULLMC text@char*@(char*)NULL@MM_NULLTXT ac- tion@char*@(char*)NULL@MM_NULLACT tag@char*@(char*)NULL@MM_NULLTAG _ The MSGVERB environment variable (for message verbosity) defines which parameters are used by the fmtmsg() function when writing a mes- sage to standard error (stderr). The value of MSGVERB is a colon-sepa- rated list of optional keywords. Valid keywords are: label, severity, text, action, and tag. These parameters may be specified in any order. See the PARAMETERS section for parameter definitions. If MSGVERB contains a keyword for a component and the component's value is not the component's null value, fmtmsg() includes that component in the message written to standard error. If MSGVERB omits a keyword for a message component, that component is omitted in the display of the message. If MSGVERB is not defined, if its value is the null string, if its value is not of the correct format, or if it contains invalid keywords, the fmtmsg() function displays all of the components. The MSGVERB setting affects only which components are selected for dis- play to standard error. All message components are included in console messages. NOTES [Digital] The following functionality does not conform to the current standards and is supported only for backward compatibility. When spec- ifying the classification component, you can combine more than one op- tion from a subclass with an option from a different subclass if you OR the values together. The SEV_LEVEL (severity level) environment vari- able can be used to define, modify, or delete severity levels other than the default. Each severity level that you define has a print string associated with it that is used by the fmtmsg function. The syntax is: SEV_LEVEL=[description[:description[: ...]]] export SEV_LEVEL The description arguments consist of three fields separated by commas as follows: description=severity_level,level,printstring The value of each field is: Specifies the severity of the level. Spec- ifies a severity level with any positive integer except 0 to 4 (the standard severity levels). Specifies the severity level message used by the fmtmsg() function whenever the severity level level is used. If the SEV_LEVEL environment variable is not set, or it has a null value, the defaults are used. If the description is not a 3-field comma separated list as described previously or if the level field specified is not a positive integer, the SEV_LEVEL environment variable setting is ignored. The SEV_LEVEL environment variable can be set in the user's shell or used in shell scripts. For example, when the environment variable SEV_LEVEL is set as follows: SEV_LEVEL=note, 5, NOTE and the fmtmsg() function is called as follows:: fmtmsg(MM_PRINT, "program:subroutine", 5, "large output file produced", "check file size before dump", "program:subroutine:002") the following message is displayed: program:subroutine: NOTE: invalid syntax TO FIX: correct the syntax program:subroutine:002 EXAMPLES The following example of fmtmsg(): fmtmsg(MM_PRINT, "program:subroutine", MM_ERROR, "invalid syntax", "read the program manpage", "program:subroutine:003"), produces a complete message in the specified message format: program:subroutine: ERROR: invalid syntax TO FIX: read the program man- page program:subroutine:003 When the environment variable MSGVERB is set as follows: MSGVERB=severity:text:action and Example 1 is used, the fmtmsg() function produces the following re- sults: ERROR: invalid syntax TO FIX: read the program manpage RETURN VALUES The fmtmsg() function returns the following values: The function was unable to generate a console message, but otherwise succeeded. The function was unable to generate a message on standard error, but other- wise succeeded. The function failed completely. The function suc- ceeded. RELATED INFORMATION Functions: printf(3) Standards: standards(5) delim off fmtmsg(3)