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

FreeBSD Manual Pages


home | help
FMTMSG(3)		 BSD Library Functions Manual		     FMTMSG(3)

     fmtmsg -- display a detailed diagnostic message

     Standard C	Library	(libc, -lc)

     #include <fmtmsg.h>

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

     The fmtmsg() function displays a detailed diagnostic message, based on
     the supplied arguments, to	stderr and/or the system console.

     The classification	argument is the	bitwise	inclusive OR of	zero or	one of
     the manifest constants from each of the classification groups below.  The
     Output classification group is an exception since both MM_PRINT and
     MM_CONSOLE	may be specified.


	     MM_PRINT	 Output	should take place on stderr.

	     MM_CONSOLE	 Output	should take place on the system	console.

     Source of Condition (Major)

	     MM_HARD	 The source of the condition is	hardware related.

	     MM_SOFT	 The source of the condition is	software related.

	     MM_FIRM	 The source of the condition is	firmware related.

     Source of Condition (Minor)

	     MM_APPL	 The condition was detected at the application level.

	     MM_UTIL	 The condition was detected at the utility level.

	     MM_OPSYS	 The condition was detected at the operating system


	     MM_RECOVER	 The application can recover from the condition.

	     MM_NRECOV	 The application is unable to recover from the condi-

     Alternatively, the	MM_NULLMC manifest constant may	be used	to specify no

     The label argument	indicates the source of	the message.  It is made up of
     two fields	separated by a colon (`:').  The first field can be up to 10
     bytes, and	the second field can be	up to 14 bytes.	 The MM_NULLLBL	mani-
     fest constant may be used to specify no label.

     The severity argument identifies the importance of	the condition.	One of
     the following manifest constants should be	used for this argument.

	   MM_HALT     The application has confronted a	serious	fault and is

	   MM_ERROR    The application has detected a fault.

	   MM_WARNING  The application has detected an unusual condition, that
		       could be	indicative of a	problem.

	   MM_INFO     The application is providing information	about a	non-
		       error condition.

	   MM_NOSEV    No severity level supplied.

     The text argument details the error condition that	caused the message.
     There is no limit on the size of this character string.  The MM_NULLTXT
     manifest constant may be used to specify no text.

     The action	argument details how the error-recovery	process	should begin.
     Upon output, fmtmsg() will	prefix "TO FIX:" to the	beginning of the
     action argument.  The MM_NULLACT manifest constant	may be used to specify
     no	action.

     The tag argument should reference online documentation for	the message.
     This usually includes the label and a unique identifying number.  An ex-
     ample tag is "BSD:ls:168".	 The MM_NULLTAG	manifest constant may be used
     to	specify	no tag.

     The fmtmsg() function returns MM_OK upon success, MM_NOMSG	to indicate
     output to stderr failed, MM_NOCON to indicate output to the system	con-
     sole failed, or MM_NOTOK to indicate output to stderr and the system con-
     sole failed.

     The MSGVERB (message verbosity) environment variable specifies which ar-
     guments to	fmtmsg() will be output	to stderr, and in which	order.
     MSGVERB should be a colon (`:') separated list of identifiers.  Valid
     identifiers include: label, severity, text, action, and tag.  If invalid
     identifiers are specified or incorrectly separated, the default message
     verbosity and ordering will be used.  The default ordering	is equivalent
     to	a MSGVERB with a value of "label:severity:text:action:tag".

     The code:

	   fmtmsg(MM_UTIL | MM_PRINT, "BSD:ls",	MM_ERROR,
	       "illegal	option -- z", "refer to	manual", "BSD:ls:001");

     will output:

	   BSD:ls: ERROR: illegal option -- z
	   TO FIX: refer to manual BSD:ls:001

     to	stderr.

     The same code, with MSGVERB set to	"text:severity:action:tag", produces:

	   illegal option -- z:	ERROR
	   TO FIX: refer to manual BSD:ls:001

     err(3), exit(3), strerror(3)

     The fmtmsg() function conforms to IEEE Std	1003.1-2001 ("POSIX.1").

     The fmtmsg() function first appeared in FreeBSD 5.0.

     Specifying	MM_NULLMC for the classification argument makes	little sense,
     since without an output specified,	fmtmsg() is unable to do anything use-

     In	order for fmtmsg() to output to	the system console, the	effective user
     must have appropriate permission to write to /dev/console.	 This means
     that on most systems fmtmsg() will	return MM_NOCON	unless the effective
     user is root.

BSD				August 5, 2002				   BSD


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

home | help