fmtmsg man page on SunOS

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

fmtmsg(3C)		 Standard C Library Functions		    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 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
		       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 iden‐
			    tifiers may be used.

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

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

			 ·  MM_HALT indicates that the application has encoun‐
			    tered  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 ordi‐
			    nary  that	might  be  a  problem  and  should  be
			    watched. Produces the print string WARNING.

			 ·  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 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
		       recovery	 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:

		       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 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
		       defined, if its value is the null string, if its	 value
		       is  not	of  the correct format, or if it contains key‐
		       words 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
		       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:

		       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 deter‐
		       mine 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
		       standard 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)

SunOS 5.10			  24 Jul 2002			    fmtmsg(3C)
[top]

List of man pages available for SunOS

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