*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> fmtmsg (3c)              


fmtmsg(3C)							    fmtmsg(3C)

NAME    [Toc]    [Back]

     fmtmsg - display a	message	on stderr or system console

SYNOPSIS    [Toc]    [Back]

     #include <fmtmsg.h>

     int fmtmsg(long classification, const  char *label, int severity,
	 const char *text, const char *action, const char *tag);

DESCRIPTION    [Toc]    [Back]

     Based on a	message's classification component, fmtmsg writes a formatted
     message to	stderr,	to the console,	or to both.

     fmtmsg can	be used	instead	of the traditional printf interface to display
     messages to stderr.  fmtmsg, in conjunction with gettxt, provides a
     simple interface for producing language-independent applications.

     A formatted message consists of up	to five	standard components as defined
     below.  The component, classification, is not part	of the standard
     message displayed to the user, but	rather defines the source of the
     message and directs the display of	the formatted message.

	   Contains identifiers	from the following groups of major
	   classifications and subclassifications.  Any	one identifier from a
	   subclass may	be used	in combination by ORing	the values together
	   with	a single identifier from a different subclass.	Two or more
	   identifiers from the	same subclass should not be used together,
	   with	the exception of identifiers from the display subclass.	 (Both
	   display subclass identifiers	may be used so that messages can be
	   displayed to	both stderr and	the system console).

	      ``Major classifications''	identify the source of the condition.
	      Identifiers are:	MM_HARD	(hardware), MM_SOFT (software),	and
	      MM_FIRM (firmware).

	      ``Message	source subclassifications'' identify the type of
	      software in which	the problem is spotted.	 Identifiers are:
	      MM_APPL (application), MM_UTIL (utility),	and MM_OPSYS
	      (operating system).

	      ``Display	subclassifications'' indicate where the	message	is to
	      be displayed.  Identifiers are: MM_PRINT to display the message
	      on the standard error stream, MM_CONSOLE to display the message
	      on the system console.  Neither, either, or both identifiers may
	      be used.

	      ``Status subclassifications'' indicate whether the application
	      will recover from	the condition.	Identifiers are: MM_RECOVER
	      (recoverable) and	MM_NRECOV (non-recoverable).

									Page 1

fmtmsg(3C)							    fmtmsg(3C)

	      An additional identifier,	MM_NULLMC, indicates that no
	      classification component is supplied for the message.

     label Identifies the source of the	message.  The format of	this component
	   is two fields separated by a	colon.	The first field	is up to 10
	   characters long; the	second is up to	14 characters.	Suggested
	   usage is that label identifies the package in which the application
	   resides as well as the program or application name.	For example,
	   the label <b>UX:cat indicates the UNIX System V	package	and the	cat

	   Indicates the seriousness of	the condition.	Identifiers for	the
	   standard levels of severity are:

	      MM_HALT indicates	that the application has encountered a severe
	      fault and	is halting.  Produces the print	string HALT.

	      MM_ERROR indicates that the application has detected a fault.
	      Produces the print string	ERROR.

	      MM_WARNING indicates a condition out of the ordinary that	might
	      be a problem and should be watched.  Produces the	print string

	      MM_INFO provides information about a condition that is not in
	      error.  Produces the print string	INFO.

	      MM_NOSEV indicates that no severity level	is supplied for	the

	   Other severity levels may be	added by using the addseverity

     text  Describes the condition that	produced the message.  The text	string
	   is not limited to a specific	size.

	   Describes the first step to be taken	in the error recovery process.
	   fmtmsg precedes each	action string with the prefix:	TO FIX:.  The
	   action string is not	limited	to a specific size.

     tag   An identifier which references on-line documentation	for the
	   message.  Suggested usage is	that tag includes the label and	a
	   unique identifying number.  A sample	tag is UX:cat:146.

   Environment Variables    [Toc]    [Back]
     There are two environment variables that control the behavior of fmtmsg:

									Page 2

fmtmsg(3C)							    fmtmsg(3C)

     MSGVERB tells fmtmsg which	message	components it is to select when
     writing messages to stderr.  The value of MSGVERB is a colon-separated
     list of optional keywords.	 MSGVERB can be	set as follows:

	  export MSGVERB

     Valid keywords are:  label, severity, text, action, and tag.  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
     when writing the message to stderr.  If MSGVERB does not include a
     keyword for a message component, that component is	not included in	the
     display of	the message.  The keywords may appear in any order.  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 keywords other than the
     valid ones	listed above, fmtmsg selects all components.

     The first time fmtmsg is called, it examines the MSGVERB environment
     variable to see which message components it is to select when generating
     a message to write	to the standard	error stream, stderr.  The values
     accepted on the initial call are saved for	future calls.

     MSGVERB affects only which	components are selected	for display to the
     standard error stream.  All message components are	included in console

     SEV_LEVEL defines severity	levels and associates print strings with them
     for use by	fmtmsg.	 The standard severity levels shown below cannot be
     modified.	Additional severity levels can also be defined,	redefined, and
     removed using addseverity [see addseverity(3C)].  If the same severity
     level is defined by both SEV_LEVEL	and addseverity, the definition	by
     addseverity is controlling.

	  0   (no severity is used)
	  1   HALT
	  2   ERROR
	  3   WARNING
	  4   INFO

     SEV_LEVEL can be set as follows:

	  export SEV_LEVEL

     description is a comma-separated list containing three fields:


     severity_keyword is a character string that is used as the	keyword	on the
     -s	severity option	to the fmtmsg command.	(This field is not used	by the
     fmtmsg function.)

									Page 3

fmtmsg(3C)							    fmtmsg(3C)

     level is a	character string that evaluates	to a positive integer (other
     than 0, 1,	2, 3, or 4, which are reserved for the standard	severity
     levels).  If the keyword severity_keyword is used,	level is the severity
     value passed on to	the fmtmsg function.

     printstring is the	character string used by fmtmsg	in the standard
     message format whenever the severity value	level is used.

     If	a description in the colon list	is not a three-field comma list, or,
     if	the second field of a comma list does not evaluate to a	positive
     integer, that description in the colon list is ignored.

     The first time fmtmsg is called, it examines the SEV_LEVEL	environment
     variable, if defined, to see whether the environment expands the levels
     of	severity beyond	the five standard levels and those defined using
     addseverity.  The values accepted on the initial call are saved for
     future calls.

   Use in Applications    [Toc]    [Back]
     One or more message components may	be systematically omitted from
     messages generated	by an application by using the null value of the
     argument for that component.

     The table below indicates the null	values and identifiers for fmtmsg

		  |Argument   Type     Null-Value    Identifier	|
		  |label      char*   (char*) NULL   MM_NULLLBL	|
		  |severity   int     0		     MM_NULLSEV	|
		  |class      long    0L	     MM_NULLMC	|
		  |text	      char*   (char*) NULL   MM_NULLTXT	|
		  |action     char*   (char*) NULL   MM_NULLACT	|
		  |tag	      char*   (char*) NULL   MM_NULLTAG	|

     Another means of systematically omitting a	component is by	omitting the
     component keyword(s) when defining	the MSGVERB environment	variable (see
     the ``Environment Variables'' section).

EXAMPLES    [Toc]    [Back]

     Example 1:

     The following example of fmtmsg:

	  fmtmsg(MM_PRINT, "UX:cat", MM_ERROR, "invalid	syntax", "refer	to
	  manual", "UX:cat:001")

     produces a	complete message in the	standard message format:

									Page 4

fmtmsg(3C)							    fmtmsg(3C)

	  UX:cat: ERROR: invalid syntax
		   TO FIX: refer to manual   UX:cat:001

     Example 2:

     When the environment variable MSGVERB is set as follows:


     and the Example 1 is used,	fmtmsg produces:

	  ERROR: invalid syntax
	  TO FIX: refer	to manual

     Example 3:

     When the environment variable SEV_LEVEL is	set as follows:


     the following call	to fmtmsg:

	  fmtmsg(MM_UTIL | MM_PRINT, "UX:cat", 5, "invalid syntax", "refer to
	  manual", "UX:cat:001")


	  UX:cat: NOTE:	invalid	syntax
		   TO FIX: refer to manual   UX:cat:001

NOTES    [Toc]    [Back]

     A slightly	different standard error message format	and a new developer
     interface,	pfmt, is being introduced as the replacement for fmtmsg.  A
     similar interface,	lfmt, is also being introduced for producing a
     standard format message and forwarding messages to	the console and/or to
     the system	message	logging	and monitoring facilities.  fmtmsg will	be
     removed at	a future time.

SEE ALSO    [Toc]    [Back]

     fmtmsg(1),	addseverity(3C), gettxt(3C), printf(3S).

DIAGNOSTICS    [Toc]    [Back]

     The exit codes for	fmtmsg are the following:

     MM_OK	 The function succeeded.

     MM_NOTOK	 The function failed completely.

     MM_NOMSG	 The function was unable to generate a message on the standard
		 error stream, but otherwise succeeded.

									Page 5

fmtmsg(3C)							    fmtmsg(3C)

     MM_NOCON	 The function was unable to generate a console message,	but
		 otherwise succeeded.

									PPPPaaaaggggeeee 6666
[ Back ]
 Similar pages
Name OS Title
dmesg FreeBSD display the system message buffer
dmesg OpenBSD display the system message buffer
folder Tru64 set folder or display current folder name (only available within the message handling system, mh)
syslog Tru64 enables and disables printing to the console device, /dev/console, by the syslogd daemon.
systty HP-UX system console interface
syscon HP-UX system console interface
console HP-UX system console interface
xconsole IRIX monitor system console messages with X
xconsole Tru64 monitor system console messages with X
dxconsole Tru64 monitor system console messages with X
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service