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

FreeBSD Manual Pages

  
 
  

home | help
msgno(3m)		     MBA Library Functions		     msgno(3m)

NAME
       msgno  -	manage error codes and associated messages across separate li-
       braries

SYNOPSIS
       #include	<mba/msgno.h>

       MMSG(fmt, ...)
       MMNO(msgno)
       MMNF(msgno, fmt,	...)

       /* Primary */
       PMSG(fmt, ...)
       PMNO(msgno)
       PMNF(msgno, fmt,	...)

       /* Additional */
       AMSG(fmt, ...)
       AMNO(msgno)
       AMNF(msgno, fmt,	...)

       extern int (*msgno_hdlr)(const char *fmt, ...);

       struct msgno_entry {
	    unsigned int msgno;
	    const char *msg;
       };

       int msgno_add_codes(struct msgno_entry *list);
       const char *msgno_msg(unsigned int msgno);
       int msgno_hdlr_stderr(const char	*fmt, ...);

DESCRIPTION
       The msgno(3m) module provides a set of macros that  when	 used  consis-
       tently will generate stacktrace-like output like	the following example:

	      src/expatls.c:97:utf8tods: Character encoding error
		src/expatls.c:449:start_fn:
		src/dom.c:405:DOM_Element_normalize:
		dump.c:30:main:	Failed to process sample.xml

       Note:  As  of  version 0.9, this	implementation no longer uses variadic
       macros -- it is strict standard C.

       Additionally this module	provides functions for	managing  error	 codes
       (or  more  generically  message numbers)	and associated messages	across
       separate	C libraries. This functionality	is very	similar	to the com_err
       library	but  with runtime message registration.	Each participating li-
       brary registers a table of messages at runtime with the msgno_add_codes
       function.  The msgno(3m)	macros are provided to dispatch	messages (e.g.
       print to	stderr).

       Note: The msgno(3m) macros operate on a	shared	buffer	and  therefore
       they are	not reentrant. Meaning they cannot not be used concurrently by
       multiple	threads.

       add_codes
	      The mnsgo_add_codes function registers an	array  of  msgno_entry
	      structures.  The array must contain at least one element and the
	      msg member of the	last element must be NULL.  Each  msgno	 value
	      must  be greater than the	previous value.	Values will be created
	      at runtime if not	provided (e.g.	all  0s	 becomes  0,1,2,3,..).
	      Create  macros  for  each	message	value by referencing the msgno
	      member like the following:

	      #define DOM_INDEX_SIZE_ERR	      dom_codes[0].msgno
	      #define DOM_DOMSTRING_SIZE_ERR	      dom_codes[1].msgno

	      struct msgno_entry dom_codes[] = {
		  { 1, "The index specified was	out of range" },
		  { 0, "The text size is out of	range" },
		  ...
		  { 0, NULL }
	      };

       msg    The msgno_msg function returns the message associated  with  the
	      msgno  parameters	 that have previously been registered with ms-
	      gno_add_codes.  If no such message has been registered, then the
	      message  "No such	msgno list" or "No such	message	in msgno list"
	      is returned.

       hdlr_stderr
	      The msgno_hdlr_stderr function writes msgno messages to  stderr.
	      It  is the default msgno message handler.	The msgno message han-
	      dler may be changed by reassigning a new function	 that  matches
	      the signature to the msgno_hdlr function pointer.

	      Tip:  If you are working on a Microsoft Windows MFC application,
	      create a msgno_hdlr function  like  the  one  below  that	 calls
	      AfxMessageBox  and  set  it to msgno_hdlr	in InitInstance.  This
	      will permit your MFC application to report errors	generated from
	      within libmba.

	      static int
	      MessageBoxHdlr(const char	*fmt, ...)
	      {
		  char mbs[4096];
		  wchar_t wcs[4096];
		  va_list ap;
		  va_start(ap, fmt);

		  _vsnprintf(mbs, 4096,	fmt, ap);
		  if (mbstowcs(wcs, mbs, 4096) != (size_t)-1) {
				 AfxMessageBox(wcs);
		  }

		  va_end(ap);
		  return 0;
	      }
	      BOOL CWutApp::InitInstance()
	      {
		  ...
		  msgno_hdlr = MessageBoxHdlr;

RETURNS
       add_codes
	      The msgno_add_codes function returns 0 if	the operation was suc-
	      cessful. Otherwise -1 is returned	and  errno  is	set  appropri-
	      ately.

       hdlr_stderr
	      The  msgno_hdlr_stderr  function	(i.e. the msgno_hdlr function)
	      returns the number of characters printed to stderr.

libmba-0.9.1			 Apr 29, 2005			     msgno(3m)

NAME | SYNOPSIS | DESCRIPTION | RETURNS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=msgno&sektion=3m&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help