*nix Documentation Project
·  Home
 +   man pages
·  Linux HOWTOs
·  FreeBSD Tips
·  *niX Forums

  man pages->IRIX man pages -> lfmt (3c)              


lfmt(3C)							      lfmt(3C)

NAME    [Toc]    [Back]

     lfmt, vlfmt -  display error message in standard format and pass to
     logging and monitoring services

SYNOPSIS    [Toc]    [Back]

     #include <pfmt.h>

     int lfmt(FILE *stream<b>, long flags<b>,	char *format<b>, .	. . /* args <b>*/);

     #include <stdarg.h>
     #include <pfmt.h>

     int vlfmt(FILE *stream<b>, long flags<b>, char *format<b>, va_list ap<b>);

DESCRIPTION    [Toc]    [Back]

     lfmt retrieves a format string from a locale-specific message database
     (unless MM_NOGET is specified) and	uses it	for printf style formatting of
     args.  The	output is displayed on stream.	If stream is NULL, no output
     is	displayed.  lfmt encapsulates the output in the	standard error message
     format (unless MM_NOSTD is	specified, in which case the output is simply

     lfmt forwards its output to the logging and monitoring facility, even if
     stream is null.  lfmt will	also display the output	on the console,	with a
     date and time stamp, when MM_CONSOLE is specified (see below).

     If	the printf format string is to be retrieved from a message database,
     the format	argument must have the following structure:


     If	MM_NOGET is specified, only the	defmsg part must be specified.

     catalog indicates the message database that contains the localized
     version of	the format string.  catalog must be limited to 14 characters.
     These characters must be selected from a set of all character values,
     excluding \0 (null) and the ASCII codes for / (slash) and : (colon).

     msgnum must be a positive number that indicates the index of the string
     into the message database.

     If	catalog	does not exist in the locale (specified	by the last call to
     setlocale using the LC_ALL	or LC_MESSAGES categories), or if the message
     number is out of bounds, lfmt attempts to retrieve	the message from the C
     locale.  If this second retrieval fails, lfmt uses	the defmsg part	of the
     format argument.

     If	catalog	is omitted, lfmt attempts to retrieve the string from the
     default catalog specified by the last call	to setcat.  In this case, the
     format argument has the following structure:

									Page 1

lfmt(3C)							      lfmt(3C)


     lfmt outputs Message not found!!\n	as the format string if:

	  - catalog is not a valid catalog name	as defined above

	  - no catalog is specified (either explicitly or via setcat)

	  - msgnum is not a positive number

	  - if no message could	be retrieved from the message databases	and
	    defmsg was omitted

     The flags determine the type of output (that is, whether the format
     should be interpreted as is or encapsulated in the	standard message
     format), and the access to	message	catalogs to retrieve a localized
     version of	format.	 The flags are composed	of several groups, and can
     take the following	values (one from each group):

     Output format control

	  MM_NOSTD     do not use the standard message format, interpret
		       format as a printf format.  Only	catalog	access control
		       flags, console display control, and logging information
		       should be specified if MM_NOSTD is used;	all other
		       flags will be ignored.

	  MM_STD       output using the	standard message format	(default,
		       value 0).

     Catalog access control

	  MM_NOGET     do not retrieve a localized version of format.  In this
		       case, only the defmsg part of the format	is specified.

	  MM_GET       retrieve	a localized version of format, from the
		       catalog,	using msgnum as	the index and defmsg as	the
		       default message (default, value 0).

     Severity (standard	message	format only)

	  MM_HALT      generates a localized version of	HALT.

	  MM_ERROR     generates a localized version of	ERROR (default,	value

	  MM_WARNING   generates a localized version of	WARNING.

	  MM_INFO      generates a localized version of	INFO.

									Page 2

lfmt(3C)							      lfmt(3C)

	  Additional severities	can be defined.	 Add-on	severities can be
	  defined with number-string pairs with	numeric	values from the	range
	  [5-255], using addsev(3C).  The numeric value	ORed with other	flags
	  will generate	the specified severity.

	  If the severity is not defined, lfmt uses the	string SEV=N where N
	  is replaced by the integer severity value passed in flags.

	  Multiple severities passed in	flags will not be detected as an
	  error.  Any combination of severities	will be	summed and the numeric
	  value	will cause the display of either a severity string (if
	  defined) or the string SEV=N (if undefined).


	  MM_ACTION    specifies an action message.  Any severity value	is
		       superseded and replaced by a localized version of TO

     Console display control

	  MM_CONSOLE	  display the message to the console in	addition to
			  the specified	stream.

	  MM_NOCONSOLE	  do not display the message to	the console in
			  addition to the specified stream (default, value 0).

     Logging information

	Major classification
		  identifies the source	of the condition.  Identifiers are:
		  MM_HARD (hardware), MM_SOFT (software), and MM_FIRM

	Message	source subclassification
		  identifies the type of software in which the problem is
		  spotted.  Identifiers	are:  MM_APPL (application), MM_UTIL
		  (utility), and MM_OPSYS (operating system).

   Standard Error Message Format    [Toc]    [Back]
     lfmt displays error messages in the following format:

	  label<b>: severity<b>: text

     If	no label was defined by	a call to setlabel, the	message	is displayed
     in	the format:

	  severity<b>: text

     If	lfmt is	called twice to	display	an error message and a helpful action
     or	recovery message, the output can look like:

									Page 3

lfmt(3C)							      lfmt(3C)

	  label<b>: severity<b>: text
	  label<b>: TO FIX: text

     vlfmt is the same as lfmt except that instead of being called with	a
     variable number of	arguments, it is called	with an	argument list as
     defined by	the stdarg.h header file.

     The stdarg.h header file defines the type va_list and a set of macros for
     advancing through a list of arguments whose number	and types may vary.
     The argument ap to	vlfmt is of type va_list.  This	argument is used with
     the stdarg.h header file macros va_start, va_arg and va_end [see
     va_start, va_arg, and va_end in stdarg(5)].  The EXAMPLE sections below
     show their	use.

     The macro va_alist	is used	as the parameter list in a function definition
     as	in the function	called error in	the example below.  The	macro
     va_start(ap<b>, ), where ap is of type va_list, must be called before	any
     attempt to	traverse and access unnamed arguments.	Calls to va_arg(ap<b>,
     atype<b>) traverse the argument list.	 Each execution	of va_arg expands to
     an	expression with	the value and type of the next argument	in the list
     ap, which is the same object initialized by va_start.  The	argument atype
     is	the type that the returned argument is expected	to be.	The va_end(ap<b>)
     macro must	be invoked when	all desired arguments have been	accessed.
     [The argument list	in ap can be traversed again if	va_start is called
     again after va_end.]  In the example below, va_arg	is executed first to
     retrieve the format string	passed to error.  The remaining	error
     arguments,	arg1, arg2, . .	., are given to	vlfmt in the argument ap.

EXAMPLES    [Toc]    [Back]

   lfmt	example	1
		"test:2:Cannot open file: %s\n", strerror(errno));

     displays the message to stderr and	to the console and makes it available
     for logging:

	  UX:test: ERROR: Cannot open file: No such file or directory

   lfmt	example	2
     lfmt(stderr, MM_INFO|MM_SOFT|MM_UTIL,
	    "test:23:test facility is enabled\n");

     displays the message to stderr and	makes it available for logging:

	  UX:test: INFO: test facility enabled

   vlfmt example
     The following demonstrates	how vlfmt could	be used	to write an errlog

									Page 4

lfmt(3C)							      lfmt(3C)

	  #include <pfmt.h>
	  #include <stdarg.h>
	  . . .
	   *   errlog should be	called like
	   *	     errlog(log_info, format, arg1, ...);
	  void errlog(long log_info, const char	*format, ...)

	      va_list ap;
	      va_start(ap, format);
	      (void) vlfmt(stderr, log_info|MM_ERROR, format, ap);
	      (void) abort();

SEE ALSO    [Toc]    [Back]

     lfmt(1), pfmt(1), addsev(3C), gettxt(3C), setcat(3C), setlabel(3C),
     setlocale(3C), printf(3S),	environ(5), stdarg(5)

DIAGNOSTICS    [Toc]    [Back]

     On	success, lfmt and vlfmt	return the number of bytes transmitted.	 On
     failure, they return a negative value:

     -1	  write	error to stream
     -2	  cannot log and/or display at console.

									PPPPaaaaggggeeee 5555
[ Back ]
 Similar pages
Name OS Title
pfmt IRIX display error message in standard format
pfmt IRIX display error message in standard format
pam_strerror FreeBSD get PAM standard error message string
pam_verror FreeBSD display an error message
pam_error FreeBSD display an error message
fmtmsg NetBSD format and display a message
fmtmsg Tru64 Display a message in the specified format
perror NetBSD write error messages to standard error
perror OpenBSD write error messages to standard error
klog IRIX kernel error logging interface
Copyright © 2004-2005 DeniX Solutions SRL
newsletter delivery service