Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages


home | help
fmtmsg(3C)		 Standard C Library Functions		    fmtmsg(3C)

       fmtmsg -	display	a message on stderr or system console

       #include	<fmtmsg.h>

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

       The fmtmsg() function writes a formatted	message	to stderr, to the con-
       sole,  or  to  both, on a message's classification component. It	can be
       used instead of the traditional printf(3C) interface  to	 display  mes-
       sages  to stderr, and in	conjunction with gettxt(3C), provides a	simple
       interface for producing language-independent applications.

       A formatted message consists of up to five standard components (	label,
       severity, text, action, and tag)	as described below. The	classification
       component 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.

       classification  Contains	identifiers from the following groups of major
		       classifications and subclassifications. Any one identi-
		       fier from a subclass may	be used	in combination by  OR-
		       ing 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 ex-
		       ception of identifiers from the display subclass. (Both
		       display	subclass  identifiers may be used so that mes-
		       sages can be displayed to both stderr  and  the	system

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

			 o  "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).

			 o  "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 iden-
			    tifiers may	be used.

			 o  "Status  subclassifications"  indicate whether the
			    application	will recover from the condition. Iden-
			    tifiers  are: MM_RECOVER (recoverable) and MM_NRE-
			    COV	(non-recoverable).

			 o  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 exam-
		       ple, the	label UX:cat indicates the UNIX	System V pack-
		       age and the cat(1) utility.

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

			 o  MM_HALT indicates that the application has encoun-
			    tered  a severe fault and is halting. Produces the
			    print string HALT.

			 o  MM_ERROR indicates that the	 application  has  de-
			    tected a fault. Produces the print string ERROR.

			 o  MM_WARNING	indicates a condition out of the ordi-
			    nary  that	might  be  a  problem  and  should  be
			    watched. Produces the print	string WARNING.

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

			 o  MM_NOSEV  indicates	that no	severity level is sup-
			    plied for the message.

		       Other severity levels may be added by  using  the  add-
		       severity() routine.

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

       action	       Describes the first step	to be taken in the  error  re-
		       covery  process.	 fmtmsg()  precedes each action	string
		       with the	prefix:	TOFIX:.	The action string is not  lim-
		       ited 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
       The MSGVERB and SEV_LEVEL environment variables control the behavior of
       fmtmsg()	as follows:

       MSGVERB	       This   variable	determines  which  message  components
		       fmtmsg()	selects	when writing messages to  stderr.  Its
		       value  is  a  colon-separated list of optional keywords
		       and 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	compo-
		       nent is not included in the display of the message. The
		       keywords	may appear in any order. If MSGVERB is not de-
		       fined, 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()  se-
		       lects all components.

		       The  first time fmtmsg()	is called, it examines MSGVERB
		       to determine which message components  are  to  be  se-
		       lected  when generating a message to write to the stan-
		       dard error stream, stderr. The values accepted  on  the
		       initial call are	saved for future calls.

		       The  MSGVERB  environment  variable  affects only those
		       components that are selected for	display	to  the	 stan-
		       dard  error stream. All message components are included
		       in console messages.

       SEV_LEVEL       This variable defines severity  levels  and  associates
		       print  strings with them	for use	by fmtmsg(). The stan-
		       dard severity levels listed below cannot	 be  modified.
		       Additional  severity  levels can	also be	defined, rede-
		       fined, and removed using	addseverity()  (see  addsever-
		       ity(3C)). If the	same severity level is defined by both
		       SEV_LEVEL and addseverity(),  the  definition  by  add-
		       severity() takes	precedence.

		       0	(no severity is	used)

		       1	HALT

		       2	ERROR

		       3	WARNING

		       4	INFO

		       The SEV_LEVEL variable can be set as follows:

		       export SEV_LEVEL

		       where  description is a comma-separated list containing
		       three fields:


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

		       The level field 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.

		       The  printstring	 field 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	deter-
		       mine whether the	 environment  expands  the  levels  of
		       severity	 beyond	the five standard levels and those de-
		       fined using addseverity(). The values accepted  on  the
		       initial call are	saved for future calls.

   Use in Applications
       One  or more message components may be systematically omitted from mes-
       sages generated by an application by using the null value of the	 argu-
       ment 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 above).

       The fmtmsg() returns the	following values:

       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.

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

       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:

       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

       See attributes(5) for descriptions of the following attributes:

       |      ATTRIBUTE	TYPE	     |	    ATTRIBUTE VALUE	   |
       |Interface Stability	     |Standard			   |
       |MT-Level		     |Safe			   |

       fmtmsg(1),  addseverity(3C),  gettxt(3C),  printf(3C),	attributes(5),

SunOS 5.10			  24 Jul 2002			    fmtmsg(3C)


Want to link to this manual page? Use this URL:

home | help