fmtmsg man page on SmartOS

Man page or keyword search:  
man Server   16655 pages
apropos Keyword Search (all sections)
Output format
SmartOS logo
[printable version]

FMTMSG(3C)							    FMTMSG(3C)

NAME
       fmtmsg - display a message on stderr or system console

SYNOPSIS
       #include <fmtmsg.h>

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

DESCRIPTION
       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  classifica‐
       tion  component	is  not	 part of the standard message displayed to the
       user, but rather defines the source of the message and directs the dis‐
       play of the formatted message.

       classification
			 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).

			     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" iden‐
				    tify 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
				    identifiers may be used.

			     o	    "Status    subclassifications"    indicate
				    whether the application will recover  from
				    the condition. Identifiers are: MM_RECOVER
				    (recoverable) and MM_NRECOV	 (non-recover‐
				    able).

			     o	    An additional identifier, MM_NULLMC, indi‐
				    cates 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 sec‐
			 ond 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 UX:cat indicates the UNIX Sys‐
			 tem V package and the cat(1) utility.

       severity
			 Indicates the seriousness of the  condition.  Identi‐
			 fiers for the standard levels of severity are:

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

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

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

			     o	    MM_INFO provides information about a  con‐
				    dition that is not in error.  Produces the
				    print string INFO.

			     o	    MM_NOSEV indicates that no severity	 level
				    is supplied 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
			 recovery  process.   fmtmsg()	precedes  each	action
			 string with the prefix: TOFIX:.  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
       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:

		      MSGVERB=[keyword[:keyword[:...]]]
		      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 writ‐
		    ing	 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 cor‐
		    rect 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 MSGVERB to
		    determine which message components are to be selected when
		    generating	a  message  to	write  to  the	standard error
		    stream, stderr. The values accepted on  the	 initial  call
		    are saved for future calls.

		    The MSGVERB environment variable affects only those compo‐
		    nents that are selected for display to the standard	 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 standard sever‐
		    ity levels listed 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 add‐
		    severity(), the definition by addseverity()	 takes	prece‐
		    dence.

		    0
			 (no severity is used)

		    1
			 HALT

		    2
			 ERROR

		    3
			 WARNING

		    4
			 INFO

		    The SEV_LEVEL variable can be set as follows:

		      SEV_LEVEL=[description[:description[:...]]]
		      export SEV_LEVEL

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

		    description=severity_keyword,level,printstring

		    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 determine
		    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
       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()
       arguments.

       ┌─────────────────────────────────────────────┐
       │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).

RETURN VALUES
       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	 stan‐
		   dard error stream, but otherwise succeeded.

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

EXAMPLES
       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:

	 MSGVERB=severity:text:action

       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:

	 SEV_LEVEL=note,5,NOTE

       the following call to fmtmsg()

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

       produces

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

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

       ┌────────────────────┬─────────────────┐
       │  ATTRIBUTE TYPE    │ ATTRIBUTE VALUE │
       ├────────────────────┼─────────────────┤
       │Interface Stability │ Standard	      │
       ├────────────────────┼─────────────────┤
       │MT-Level	    │ Safe	      │
       └────────────────────┴─────────────────┘

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

				 Jul 24, 2002			    FMTMSG(3C)
[top]

List of man pages available for SmartOS

Copyright (c) for man pages and the logo by the respective OS vendor.

For those who want to learn more, the polarhome community provides shell access and support.

[legal] [privacy] [GNU] [policy] [cookies] [netiquette] [sponsors] [FAQ]
Tweet
Polarhome, production since 1999.
Member of Polarhome portal.
Based on Fawad Halim's script.
....................................................................
Vote for polarhome
Free Shell Accounts :: the biggest list on the net