Skip to content

FreeType » Docs » Error Codes » Error Enumerations

# Error Enumerations

## Synopsis

The header file `fterrors.h` (which is automatically included by `freetype.h` defines the handling of FreeType's enumeration constants. It can also be used to generate error message strings with a small macro trick explained below.

Error Formats

The configuration macro `FT_CONFIG_OPTION_USE_MODULE_ERRORS` can be defined in `ftoption.h` in order to make the higher byte indicate the module where the error has happened (this is not compatible with standard builds of FreeType 2, however). See the file `ftmoderr.h` for more details.

Error Message Strings

Error definitions are set up with special macros that allow client applications to build a table of error message strings. The strings are not included in a normal build of FreeType 2 to save space (most client applications do not use them).

To do so, you have to define the following macros before including this file.

      FT_ERROR_START_LIST

This macro is called before anything else to define the start of the error list. It is followed by several `FT_ERROR_DEF` calls.

      FT_ERROR_DEF( e, v, s )

This macro is called to define one single error. ‘e’ is the error code identifier (e.g., `Invalid_Argument`), ‘v’ is the error's numerical value, and ‘s’ is the corresponding error string.

      FT_ERROR_END_LIST

This macro ends the list.

Additionally, you have to undefine `FTERRORS_H_` before #including this file.

Here is a simple example.

      #undef FTERRORS_H_
      #define FT_ERRORDEF( e, v, s )  { e, s },
      #define FT_ERROR_START_LIST     {
      #define FT_ERROR_END_LIST       { 0, NULL } };

      const struct
      {
        int          err_code;
        const char*  err_msg;
      } ft_errors[] =

      #include <freetype/fterrors.h>

An alternative to using an array is a switch statement.

      #undef FTERRORS_H_
      #define FT_ERROR_START_LIST     switch ( error_code ) {
      #define FT_ERRORDEF( e, v, s )    case v: return s;
      #define FT_ERROR_END_LIST       }

If you use `FT_CONFIG_OPTION_USE_MODULE_ERRORS`, `error_code` should be replaced with `FT_ERROR_BASE(error_code)` in the last example.

## FT_Error_String

Defined in FT_ERRORS_H (freetype/fterrors.h).

      FT_EXPORT( const char* )
      FT_Error_String( FT_Error  error_code );

Retrieve the description of a valid FreeType error code.

#### input

error_code | A valid FreeType error code.

#### return

A C string or `NULL`, if any error occurred.

#### note

FreeType has to be compiled with `FT_CONFIG_OPTION_ERROR_STRINGS` or `FT_DEBUG_LEVEL_ERROR` to get meaningful descriptions. ‘error_string’ will be `NULL` otherwise.

Module identification will be ignored:

      strcmp( FT_Error_String(  FT_Err_Unknown_File_Format ),
              FT_Error_String( BDF_Err_Unknown_File_Format ) ) == 0;