libxml2: xmlerror.h File Reference

libxml2

Loading...
Searching...
No Matches
Data Structures | Macros | Typedefs | Enumerations | Functions
xmlerror.h File Reference

Error handling. More...

## Data Structures
struct | _xmlError
| An object containing information about an error. More...

## Macros
#define | initGenericErrorDefaultFunc(h)
| Set generic error callback.
#define | xmlLastError (*__xmlLastError())
| Thread-local variable containing the last reported error.
#define | xmlGenericError (*__xmlGenericError())
| Thread-local variable containing the generic error callback.
#define | xmlGenericErrorContext (*__xmlGenericErrorContext())
| Thread-local variable containing user data for the generic error handler.
#define | xmlStructuredError (*__xmlStructuredError())
| Thread-local variable containing the structured error callback.
#define | xmlStructuredErrorContext (*__xmlStructuredErrorContext())
| Thread-local variable containing user data for the structured error handler.

## Typedefs
typedef struct _xmlError | xmlError
| Structured error.
typedef void(*) | xmlGenericErrorFunc(void *ctx, const char *msg,...)
| Generic error callback.
typedef void(*) | xmlStructuredErrorFunc(void *userData, const xmlError *error)
| Structured error callback receiving an xmlError.

## Enumerations
enum | xmlErrorLevel
| Indicates the level of an error. More...
enum | xmlErrorDomain
| Indicates where an error may have come from. More...
enum | xmlParserErrors
| Error codes. More...

## Functions
void | xmlSetGenericErrorFunc (void *ctx, xmlGenericErrorFunc handler)
| Set the thread-local "generic" handler and context for error messages.
void | xmlSetStructuredErrorFunc (void *ctx, xmlStructuredErrorFunc handler)
| Set the thread-local "structured" handler and context for error messages.
void | xmlThrDefSetGenericErrorFunc (void *ctx, xmlGenericErrorFunc handler)
| Set per-thread default value.
void | xmlThrDefSetStructuredErrorFunc (void *ctx, xmlStructuredErrorFunc handler)
| Set per-thread default value.
void | xmlParserError (void *ctx, const char *msg,...)
| This is the default SAX error handler, but it will never be called.
void | xmlParserWarning (void *ctx, const char *msg,...)
| This is the default SAX warning handler, but it will never be called.
void | xmlParserValidityError (void *ctx, const char *msg,...)
| This is the default validity error handler, but it will never be called.
void | xmlParserValidityWarning (void *ctx, const char *msg,...)
| This is the default validity warning handler, but it will never be called.
void | xmlParserPrintFileInfo (struct _xmlParserInput *input)
| Displays the associated file and line information for the current input.
void | xmlParserPrintFileContext (struct _xmlParserInput *input)
| Displays current context within the input content for error reporting.
void | xmlFormatError (const xmlError *err, xmlGenericErrorFunc channel, void *data)
| Report a formatted error to a printf-like callback.
const xmlError * | xmlGetLastError (void)
| Get the last error raised in this thread.
void | xmlResetLastError (void)
| Reset the last error to success.
const xmlError * | xmlCtxtGetLastError (void *ctx)
| Get the last error raised.
void | xmlCtxtResetLastError (void *ctx)
| Reset the last parser error to success.
void | xmlResetError (xmlError *err)
| Reset the error to success.
int | xmlCopyError (const xmlError *from, xmlError *to)
| Copy an error.

## Detailed Description

Error handling.

API for error reporting and callbacks.

Copyright
  See Copyright for the status of this software.

Author
  Daniel Veillard

## Macro Definition Documentation

## ◆ initGenericErrorDefaultFunc

#define initGenericErrorDefaultFunc | ( |  | h | ) |

Value:
xmlSetGenericErrorFunc(NULL, (h) ? *((xmlGenericErrorFunc *) (h)) : NULL)
xmlSetGenericErrorFunc
void xmlSetGenericErrorFunc(void *ctx, xmlGenericErrorFunc handler)
Set the thread-local "generic" handler and context for error messages.
Definition error.c:272
xmlGenericErrorFunc
void(*) xmlGenericErrorFunc(void *ctx, const char *msg,...)
Generic error callback.
Definition xmlerror.h:944

Set generic error callback.

Deprecated
  Use xmlSetGenericErrorFunc

## ◆ xmlGenericError

#define xmlGenericError (*__xmlGenericError())

Thread-local variable containing the generic error callback.

Deprecated
  See xmlSetStructuredErrorFunc().

## ◆ xmlGenericErrorContext

#define xmlGenericErrorContext (*__xmlGenericErrorContext())

Thread-local variable containing user data for the generic error handler.

Deprecated
  See xmlSetStructuredErrorFunc().

## ◆ xmlLastError

#define xmlLastError (*__xmlLastError())

Thread-local variable containing the last reported error.

Deprecated
  Use xmlGetLastError().

## ◆ xmlStructuredError

#define xmlStructuredError (*__xmlStructuredError())

Thread-local variable containing the structured error callback.

Deprecated
  See xmlSetStructuredErrorFunc().

## ◆ xmlStructuredErrorContext

#define xmlStructuredErrorContext (*__xmlStructuredErrorContext())

Thread-local variable containing user data for the structured error handler.

Deprecated
  See xmlSetStructuredErrorFunc().

## Typedef Documentation

## ◆ xmlGenericErrorFunc

typedef void(*) xmlGenericErrorFunc(void *ctx, const char *msg,...)

Generic error callback.

Deprecated
  in favor of structured errors.

Parameters

  ctx | user data
  msg | printf-like format string
  ... | arguments to format

## ◆ xmlStructuredErrorFunc

typedef void(*) xmlStructuredErrorFunc(void *userData, const xmlError *error)

Structured error callback receiving an xmlError.

Parameters

  userData | user provided data for the error callback
  error | the error being raised

## Enumeration Type Documentation

## ◆ xmlErrorDomain

enum xmlErrorDomain

Indicates where an error may have come from.

Enumerator
XML_FROM_NONE | Unknown.
XML_FROM_PARSER | The XML parser.
XML_FROM_TREE | The tree module (unused).
XML_FROM_NAMESPACE | The XML Namespace module.
XML_FROM_DTD | The XML DTD validation with parser context.
XML_FROM_HTML | The HTML parser.
XML_FROM_MEMORY | The memory allocator (unused).
XML_FROM_OUTPUT | The serialization code.
XML_FROM_IO | The Input/Output stack.
XML_FROM_FTP | The FTP module (unused).
XML_FROM_HTTP | The HTTP module (unused).
XML_FROM_XINCLUDE | The XInclude processing.
XML_FROM_XPATH | The XPath module.
XML_FROM_XPOINTER | The XPointer module.
XML_FROM_REGEXP | The regular expressions module.
XML_FROM_DATATYPE | The W3C XML Schemas Datatype module.
XML_FROM_SCHEMASP | The W3C XML Schemas parser module.
XML_FROM_SCHEMASV | The W3C XML Schemas validation module.
XML_FROM_RELAXNGP | The Relax-NG parser module.
XML_FROM_RELAXNGV | The Relax-NG validator module.
XML_FROM_CATALOG | The Catalog module.
XML_FROM_C14N | The Canonicalization module.
XML_FROM_XSLT | The XSLT engine from libxslt (unused).
XML_FROM_VALID | The XML DTD validation with valid context.
XML_FROM_CHECK | The error checking module (unused).
XML_FROM_WRITER | The xmlwriter module.
XML_FROM_MODULE | The dynamically loaded module module (unused).
XML_FROM_I18N | The module handling character conversion (unused).
XML_FROM_SCHEMATRONV | The Schematron validator module.
XML_FROM_BUFFER | The buffers module (unused).
XML_FROM_URI | The URI module (unused).

## ◆ xmlErrorLevel

enum xmlErrorLevel

Indicates the level of an error.

Enumerator
XML_ERR_NONE | Success.
XML_ERR_WARNING | A warning. When parsing XML, warnings are only reported to error handlers.
XML_ERR_ERROR | An error. When parsing XML, this is used for recoverable errors like namespace errors validity errors when validating certain undeclared entities ID uniqueness and xml:id errors Note that some recoverable errors in the sense of the XML spec are reported as warnings. In other contexts, this may be used for unrecoverable errors.
XML_ERR_FATAL | A fatal error. When parsing XML, a "fatal error" according to the XML spec. This typically means that the document isn't well-formed. This also includes OOM and I/O errors, resource limit exhaustion, unexpected errors from other libraries and invalid argument errors.

## ◆ xmlParserErrors

enum xmlParserErrors

Error codes.

Note that only some codes are documented.

Enumerator
XML_ERR_OK | Success.
XML_ERR_INTERNAL_ERROR | Internal assertion failure.
XML_ERR_NO_MEMORY | Out of memory.
XML_ERR_UNSUPPORTED_ENCODING | Unsupported character encoding.
XML_ERR_RESOURCE_LIMIT | Internal resource limit like maximum amplification factor exceeded.
XML_ERR_ARGUMENT | Invalid argument.
XML_ERR_SYSTEM | Unexpected error from the OS or an external library.
XML_IO_ENOENT | File not found.

## Function Documentation

## ◆ xmlCopyError()

int xmlCopyError | ( | const xmlError * | from,
|  | xmlError * | to )

Copy an error.

Parameters

  from | a source error
  to | a target error

Returns
  0 in case of success and -1 in case of error.

## ◆ xmlCtxtGetLastError()

const xmlError * xmlCtxtGetLastError | ( | void * | ctx | ) |

Get the last error raised.

Note that the XML parser typically doesn't stop after encountering an error and will often report multiple errors. Most of the time, the last error isn't useful. Future versions might return the first parser error instead.

Parameters

  ctx | an XML parser context

Returns
  NULL if no error occurred or a pointer to the error

## ◆ xmlCtxtResetLastError()

void xmlCtxtResetLastError | ( | void * | ctx | ) |

Reset the last parser error to success.

This does not change the well-formedness status.

Parameters

  ctx | an XML parser context

## ◆ xmlFormatError()

void xmlFormatError | ( | const xmlError * | err,
|  | xmlGenericErrorFunc | channel,
|  | void * | data )

Report a formatted error to a printf-like callback.

This can result in a verbose multi-line report including additional information from the parser context.

Since
  2.13.0

Parameters

  err | the error
  channel | callback
  data | user data for callback

## ◆ xmlGetLastError()

const xmlError * xmlGetLastError | ( | void |  | ) |

Get the last error raised in this thread.

Returns
  a pointer to the error

## ◆ xmlParserError()

void xmlParserError | ( | void * | ctx,
|  | const char * | msg,
|  |  | ... )

This is the default SAX error handler, but it will never be called.

If it isn't replaced by the user, errors will be handled by xmlFormatError.

Deprecated
  Do not call directly.

Format an error message with additional detail from the parser context and print to generic error handler.

Parameters

  ctx | an XML parser context
  msg | printf-like format string
  ... | arguments to format

## ◆ xmlParserPrintFileContext()

void xmlParserPrintFileContext | ( | struct _xmlParserInput * | input | ) |

Displays current context within the input content for error reporting.

Deprecated
  Use xmlFormatError.

Parameters

  input | an xmlParserInput input

## ◆ xmlParserPrintFileInfo()

void xmlParserPrintFileInfo | ( | struct _xmlParserInput * | input | ) |

Displays the associated file and line information for the current input.

Deprecated
  Use xmlFormatError.

Parameters

  input | an xmlParserInput input

## ◆ xmlParserValidityError()

void xmlParserValidityError | ( | void * | ctx,
|  | const char * | msg,
|  |  | ... )

This is the default validity error handler, but it will never be called.

If it isn't replaced by the user, errors will be handled by xmlFormatError.

Deprecated
  Do not call directly.

Format an error message with additional detail from the parser context and print to generic error handler.

Parameters

  ctx | an XML parser context
  msg | printf-like format string
  ... | arguments to format

## ◆ xmlParserValidityWarning()

void xmlParserValidityWarning | ( | void * | ctx,
|  | const char * | msg,
|  |  | ... )

This is the default validity warning handler, but it will never be called.

If it isn't replaced by the user, warnings will be handled by xmlFormatError.

Deprecated
  Do not call directly.

Format an warning message with additional detail from the parser context and print to generic error handler.

Parameters

  ctx | an XML parser context
  msg | printf-like format string
  ... | arguments to format

## ◆ xmlParserWarning()

void xmlParserWarning | ( | void * | ctx,
|  | const char * | msg,
|  |  | ... )

This is the default SAX warning handler, but it will never be called.

If it isn't replaced by the user, warnings will be handled by xmlFormatError.

Deprecated
  Do not call directly.

Format an warning message with additional detail from the parser context and print to generic error handler.

Parameters

  ctx | an XML parser context
  msg | printf-like format string
  ... | arguments to format

## ◆ xmlResetError()

void xmlResetError | ( | xmlError * | err | ) |

Reset the error to success.

Parameters

  err | pointer to the error

## ◆ xmlSetGenericErrorFunc()

void xmlSetGenericErrorFunc | ( | void * | ctx,
|  | xmlGenericErrorFunc | handler )

Set the thread-local "generic" handler and context for error messages.

Deprecated
  See xmlSetStructuredErrorFunc for alternatives.

If you only want to disable parser errors being printed to stderr, use xmlParserOption XML_PARSE_NOERROR.

The generic error handler will only receive fragments of error messages which should be concatenated or printed to a stream.

If handler is NULL, use the built-in default handler which prints to stderr.

Since this is a thread-local setting, it's a good idea to reset the error handler to its default value after collecting the errors you're interested in. To get the original values, you have to access xmlGenericError and xmlGenericErrorContext directly, making this function kind of useless.

For multi-threaded applications, this must be set separately for each thread.

Parameters

  ctx | the new error handling context
  handler | the new handler function

## ◆ xmlSetStructuredErrorFunc()

void xmlSetStructuredErrorFunc | ( | void * | ctx,
|  | xmlStructuredErrorFunc | handler )

Set the thread-local "structured" handler and context for error messages.

Deprecated
  Use a per-context error handler.

If you only want to disable parser errors being printed to stderr, use xmlParserOption XML_PARSE_NOERROR.

It's recommended to use the per-context error handlers instead:

- xmlCtxtSetErrorHandler (since 2.13.0)
- xmlTextReaderSetStructuredErrorHandler
- xmlXPathSetErrorHandler (since 2.13.0)
- xmlXIncludeSetErrorHandler (since 2.13.0)
- xmlSchemaSetParserStructuredErrors
- xmlSchemaSetValidStructuredErrors
- xmlRelaxNGSetParserStructuredErrors
- xmlRelaxNGSetValidStructuredErrors

If handler is NULL, the error handler is deactivated.

The structured error handler takes precedence over "generic" handlers, even per-context generic handlers.

Since this is a thread-local setting, it's a good idea to reset the error handler to its default value after collecting the errors you're interested in. To get the original values, you have to access xmlStructuredError and xmlStructuredErrorContext directly, making this function kind of useless.

For multi-threaded applications, this must be set separately for each thread.

Parameters

  ctx | the new error handling context
  handler | the new handler function

## ◆ xmlThrDefSetGenericErrorFunc()

void xmlThrDefSetGenericErrorFunc | ( | void * | ctx,
|  | xmlGenericErrorFunc | handler )

Set per-thread default value.

Deprecated
  Call xmlSetGenericErrorFunc in each thread.

Parameters

  ctx | user data
  handler | error handler

## ◆ xmlThrDefSetStructuredErrorFunc()

void xmlThrDefSetStructuredErrorFunc | ( | void * | ctx,
|  | xmlStructuredErrorFunc | handler )

Set per-thread default value.

Deprecated
  Call xmlSetStructuredErrorFunc in each thread.

Parameters

  ctx | user data
  handler | error handler