Unix/Linux Go Back    


Linux 2.6 - man page for fmtmsg (linux section 3posix)

Linux & Unix Commands - Search Man Pages
Man Page or Keyword Search:   man
Select Man Page Set:       apropos Keyword Search (sections above)


FMTMSG(P)			    POSIX Programmer's Manual				FMTMSG(P)

NAME
       fmtmsg  - display a message in the specified format on standard error and/or a system con-
       sole

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 shall display messages in a specified format instead of  the  tradi-
       tional printf() function.

       Based  on  a  message's classification component, fmtmsg() shall write a formatted message
       either to standard error, to the console, or to both.

       A formatted message consists of up to five components as  defined  below.   The	component
       classification  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.

       classification
	      Contains the sum of identifying  values  constructed  from  the  constants  defined
	      below.  Any one identifier from a subclass may be used in combination with a single
	      identifier from a different subclass.  Two or more identifiers from the  same  sub-
	      class  should not be used together, with the exception of identifiers from the dis-
	      play subclass. (Both display subclass identifiers may be used so that messages  can
	      be displayed to both standard error and the system console.)

       Major Classifications

	      Identifies  the  source  of  the	condition.  Identifiers  are: MM_HARD (hardware),
	      MM_SOFT (software), and MM_FIRM (firmware).

       Message Source Subclassifications

	      Identifies the type of software in which the problem is detected.  Identifiers are:
	      MM_APPL (application), MM_UTIL (utility), and MM_OPSYS (operating system).

       Display Subclassifications

	      Indicates  where	the message is to be displayed. Identifiers are: MM_PRINT to dis-
	      play the message on the standard error stream, MM_CONSOLE to display the message on
	      the system console. One or both identifiers may be used.

       Status Subclassifications

	      Indicates whether the application can recover from the condition.  Identifiers are:
	      MM_RECOVER (recoverable) and MM_NRECOV (non-recoverable).

       An additional identifier, MM_NULLMC, indicates that no classification  component  is  sup-
       plied for the message.

       label  Identifies  the  source  of  the	message.  The format is two fields separated by a
	      colon. The first field is up to 10 bytes, the second is up to 14 bytes.

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

       MM_HALT
	      Indicates  that the application has encountered a severe fault and is halting. Pro-
	      duces the string "HALT" .

       MM_ERROR
	      Indicates that the application has detected a fault. Produces the string "ERROR" .

       MM_WARNING
	      Indicates a condition that is out of the ordinary, that might  be  a  problem,  and
	      should be watched. Produces the string "WARNING" .

       MM_INFO
	      Provides	information  about  a condition that is not in error. Produces the string
	      "INFO" .

       MM_NOSEV
	      Indicates that no severity level is supplied for the message.

       text   Describes the error condition that produced the message. The  character  string  is
	      not  limited  to	a  specific size. If the character string is empty, then the text
	      produced is unspecified.

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

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

       The MSGVERB environment variable (for message  verbosity)  shall  determine  for  fmtmsg()
       which  message  components  it  is  to select when writing messages to standard error. The
       value of MSGVERB shall be a colon-separated list of optional keywords. 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() shall include that  com-
       ponent  in  the	message  when  writing the message to standard error. If MSGVERB does not
       include a keyword for a message component, that component shall not  be	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  con-
       tains  keywords	other  than the valid ones listed above, fmtmsg() shall select all compo-
       nents.

       MSGVERB shall determine which components are selected for display to standard  error.  All
       message components shall be included in console messages.

RETURN VALUE
       The fmtmsg() function shall return one of 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 standard error, but otherwise suc-
	      ceeded.

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

ERRORS
       None.

       The following sections are informative.

EXAMPLES
	1. The following example of fmtmsg():

	   fmtmsg(MM_PRINT, "XSI:cat", MM_ERROR, "illegal option",
	   "refer to cat in user's reference manual", "XSI:cat:001")

       produces a complete message in the specified message format:

	      XSI:cat: ERROR: illegal option
	      TO FIX: refer to cat in user's reference manual XSI:cat:001

	2. When the environment variable MSGVERB is set as follows:

	   MSGVERB=severity:text:action

       and Example 1 is used, fmtmsg() produces:

	      ERROR: illegal option
	      TO FIX: refer to cat in user's reference manual

APPLICATION USAGE
       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.

RATIONALE
       None.

FUTURE DIRECTIONS
       None.

SEE ALSO
       printf() , the Base Definitions volume of IEEE Std 1003.1-2001, <fmtmsg.h>

COPYRIGHT
       Portions  of  this  text  are  reprinted  and  reproduced in electronic form from IEEE Std
       1003.1, 2003 Edition, Standard for Information Technology  --  Portable	Operating  System
       Interface  (POSIX), The Open Group Base Specifications Issue 6, Copyright (C) 2001-2003 by
       the Institute of Electrical and Electronics Engineers, Inc and  The  Open  Group.  In  the
       event  of  any  discrepancy  between this version and the original IEEE and The Open Group
       Standard, the original IEEE and The Open Group Standard is the referee document. The orig-
       inal Standard can be obtained online at http://www.opengroup.org/unix/online.html .

IEEE/The Open Group			       2003					FMTMSG(P)
Unix & Linux Commands & Man Pages : ©2000 - 2018 Unix and Linux Forums


All times are GMT -4. The time now is 09:28 AM.