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

FreeBSD Manual Pages

  
 
  

home | help 
ERROR(3ast)							     ERROR(3ast)

NAME
     error - error and debug trace message formatter

SYNOPSIS
     #include <error.h>

     Error_info_t error_info;

     void	  error(int level, ...);
     void	  errorv(const char* library, int level, va_alist args);
     int	  errormsg(const char* dictionary, int level, ...);

     #include <debug.h>

     debug(statement)
     message((int level, ...))
     messagef((void* handle, void* discipline, int level, ...))

DESCRIPTION
     error  is the error and debug trace message formatter.  level is the sever-
     ity level.  Messages with level <	error_info.trace  are  suppressed.   er-
     ror_info.trace  is  initially  0.	The remaining arguments are passed on to
     printf.  A newline is appended to the message text, so none  should  appear
     in the printf format.  If error_info.id is not 0 then messages with level >
     0 are prefixed by error_info.id:.

     Before  the  message  text  is output to standard error it is passed to the
     function char* ERROR_translate(const char* text, int flag).  By default ER-
     ROR_translate returns the text argument, but on some systems it may do lan-
     guage translation via lookup on the original source text.	(error calls ER-
     ROR_translate with a 0 flag argument).

     level may be one of:

     <0     Negative values are for debug tracing.  Debug messages are	prefixed
	    with   debuglevel.	 If  errno  !=	error_info.last_errno  then  er-
	    ror_info.last_errno is set to errno and the error text for errno  is
	    appended to the message.

     ERROR_INFO [0]
	    Information only; no prefixes are added to the message.

     ERROR_WARNING [1]
	    warning: is added after error_info.id and error_info.warnings is in-
	    cremented.

     ERROR_ERROR [2]
	    (soft error) error_info.errors is incremented.

     >= ERROR_FATAL [3]
	    (hard  error)  error_info.errors is incremented and exit(level-2) is
	    called after the message is emitted.

     ERROR_PANIC [130]
	    (unrecoverable internal error) panic: is added after error_info.id.

     The following may be inclusive-or'd into level for alternate behavior:

     ERROR_SYSTEM
	    The error text for errno is appended to the message.

     ERROR_OUTPUT
	    The next argument is the file descriptor  where  the  error  message
	    should be emitted.

     ERROR_SFIO_OUT
	    The  next argument is the Sfio stream where the error message should
	    be emitted.

     ERROR_SOURCE
	    Then next two arguments are a file name and  line  number  that  are
	    added to the message after error_info.id.

     ERROR_USAGE
	    A usage message is emitted.

     ERROR_PROMPT
	    The trailing newline is suppressed.

     ERROR_NOID
	    The error_info.id prefix is suppressed.

     ERROR_LIBRARY
	    The message is from a library routine.

ENVIRONMENT
     The  elements  of the global struct error_info control error output and ac-
     tions.  Parts of error_info can be initialized from the ERROR_OPTIONS envi-
     ronment variable.	ERROR_OPTIONS contains space separated name[=value]  op-
     tions, described below.

     int core
	    If	error_info.core  !=  0 then level >= error_info.core generates a
	    core dump.	Initialized by
	    ERROR_OPTIONS="core=level"
	    where level can be a number or one of error, fatal, or  panic.   er-
	    ror_info.core is a handy way to get a stack trace at the exact point
	    of error.

     int error_info.trace
	    If error_info.trace != 0 and level < error_info.trace then the error
	    message text is suppressed.  exit() may still be called if appropri-
	    ate for level.  Initialized by
	    ERROR_OPTIONS="trace=level"
	    where error_info.trace is set to the negative of level.

     Library error messages, suppressed by default, are enabled by
     ERROR_OPTIONS="library"
     The system errno message text can be forced for each message by
     ERROR_OPTIONS="system"

EXTENDED DESCRIPTION
     <debug.h>	provides  debugging  message macros when DEBUG or _BLD_DEBUG are
     defined (_BLD_DEBUG is defined by the Mamfiles when the  -G  a.k.a.   --de-
     bug-symbols  option  is  passed  to mamake(1), which the package(1) command
     does automatically when given the argument debug=1).  All of the macros ex-
     pand to nothing when both DEBUG and _BLD_DEBUG are not defined.   Otherwise
     debug  expands  its  arg and messagef and message call errorf and error re-
     spectively if error_info.trace<0.	Notice that  messagef  and  message  are
     macro hacks that require double parentheses ((...)) around the arguments.

EXAMPLE
     To  enable  debugging  message level -3, library messages, and system errno
     text for all commands:
     export ERROR_OPTIONS="trace=3 library system"

								     ERROR(3ast)

Want to link to this manual page? Use this URL:
<https://man.freebsd.org/cgi/man.cgi?query=error&sektion=3&manpath=FreeBSD+Ports+15.1.quarterly>

home | help