File: gettext.info,  Node: Error Handling,  Next: po_file_t API,  Up: libgettextpo

10.13.1 Error Handling
----------------------

   Error management is performed through callbacks provided by the user
of the library.  They are provided through a parameter with the
following type:

 -- Data Type: struct po_xerror_handler
     Its pointer is defined as ‘po_xerror_handler_t’.  Contains two
     fields, ‘xerror’ and ‘xerror2’, with the following function
     signatures.

 -- Function: void xerror (int SEVERITY, po_message_t MESSAGE,
          const char *FILENAME, size_t LINENO, size_t COLUMN,
          int MULTILINE_P, const char *MESSAGE_TEXT)

     This function is called to signal a problem of the given SEVERITY.
     It _must not return_ if SEVERITY is ‘PO_SEVERITY_FATAL_ERROR’.

     MESSAGE_TEXT is the problem description.  When MULTILINE_P is true,
     it can contain multiple lines of text, each terminated with a
     newline, otherwise a single line.

     MESSAGE and/or FILENAME and LINENO indicate where the problem
     occurred:

        • If FILENAME is ‘NULL’, FILENAME and LINENO and COLUMN should
          be ignored.

        • If LINENO is ‘(size_t)(-1)’, LINENO and COLUMN should be
          ignored.

        • If COLUMN is ‘(size_t)(-1)’, it should be ignored.

 -- Function: void xerror2 (int SEVERITY, po_message_t MESSAGE1,
          const char *FILENAME1, size_t LINENO1, size_t COLUMN1,
          int MULTILINE_P1, const char *MESSAGE_TEXT1,
          po_message_t MESSAGE2, const char *FILENAME2, size_t LINENO2,
          size_t COLUMN2, int MULTILINE_P2, const char *MESSAGE_TEXT2)

     This function is called to signal a problem of the given SEVERITY
     that refers to two messages.  It _must not return_ if SEVERITY is
     ‘PO_SEVERITY_FATAL_ERROR’.

     It is similar to two calls to xerror.  If possible, an ellipsis can
     be appended to MESSAGE_TEXT1 and prepended to MESSAGE_TEXT2.