<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="errors">

  <info><link type="guide" xref="index#intro"/></info>
  <title>Handling Errors</title>

  <p>Many functions in Libbson can result in errors. To simplify this, Libbson contains a structure called <code xref="bson_error_t">bson_error_t</code>. This structure enapsulates an error from the underlying system and can be passed back up the stack. Think of it as an exception as an <code>out parameter</code>.</p>

  <p>The structure contains <code>domain</code> and <code>code</code> fields that can be used to check for specific error conditions. The value of these fields is API specific. If you simply want to print an error message, use the <code>message</code> field of <code xref="bson_error_t">bson_error_t</code>.</p>

  <p>Functions that can result in error specify the return value that indicates the <code>error</code> out parameter was initialized. Typically this is <code>0</code> or <code>NULL</code>, but may sometimes be <code>-1</code> depending on the API.</p>

  <p>This structure should be stack-allocated and requires no explicit freeing.</p>

</page>
