NAME

       waffle_error, waffle_error_get_info, waffle_error_get_code, waffle_error_to_string -
       Thread-local error state

SYNOPSIS

       #include <waffle.h>

       enum waffle_error {...};

       struct waffle_error_info {
           enum waffle_error code;
           const char *message;
           size_t message_length;
       };

       const struct waffle_error_info* waffle_error_get_info(void);

       enum waffle_error waffle_error_get_code(void);

       const char* waffle_error_to_string(enum waffle_errore);

DESCRIPTION

       Waffle functions usually return either a bool, in which false indicates failure, or a
       pointer, in which null indicates failure. In addition to returning a flag indicating
       failure, most functions also clear and then set some thread-local error state.

       The only functions that do not alter waffle's error state are listed here and are
       explicitly documented as such. All functions listed here can be called before waffle has
       been successfully initialized with waffle_init(3)

       struct waffle_error_info
           This struct contains the user-visible portion of waffle's thread-local error state.

           code may be any token from enum waffle_error.

           message often contains a descriptive message about the error. It is never null, though
           it may be the empty string.

           message_length is the length of message according to strlen(3).

       waffle_error_to_string()
           Convert a waffle_error token to a string. For example, convert WAFFLE_ERROR_UNKNOWN to
           "WAFFLE_ERROR_UNKNOWN". Return null if the token is not a valid error token.

           This function always sets the error code to WAFFLE_ERROR_NONE.

       waffle_error_get_info()
           Get information about the current thread's error state.

           This function never returns null. The returned pointer becomes invalid when the
           thread-local error state changes.

           This function does not alter waffle's error state.

       waffle_error_get_code()
           Get the current thread's error code. Calling this function is equivalent to obtaining
           the error code with waffle_error_get_info()->code.

           This function does not alter waffle's error state.

       enum waffle_error
           For reference, below is the complete list of waffle's error codes.

           WAFFLE_NO_ERROR = 0x00
               The function succeeded.

           WAFFLE_ERROR_FATAL = 0x01
               Waffle encountered a fatal error. All future waffle calls result in undefined
               behavior.

           WAFFLE_ERROR_UNKNOWN = 0x02
               Waffle encountered an error for which it lacks an error code. This is usually
               produced when an underlying native call, such as XOpenDisplay(3), fails for an
               unknown reason.

           WAFFLE_ERROR_INTERNAL = 0x03
               You found a bug in waffle. Please report it. The error message, obtained by
               waffle_error_get_info(), should contain a description of the bug.

           WAFFLE_ERROR_BAD_ALLOC = 0x04
               Waffle failed to allocate memory.

           WAFFLE_ERROR_NOT_INITIALIZED = 0x05
               The failed function requires waffle to be initialized with waffle_init(3).

           WAFFLE_ERROR_ALREADY_INITIALIZED = 0x06
               If waffle has already been initialized by a successful call to waffle_init(3),
               then subsequent calls to waffle_init() produce this error.

           WAFFLE_ERROR_BAD_ATTRIBUTE = 0x08
               An unrecognized attribute name or attribute value was passed in an attribute list.

           WAFFLE_ERROR_BAD_PARAMETER = 0x10
               The failed function was passed an invalid argument.

           WAFFLE_ERROR_BAD_DISPLAY_MATCH = 0x11
               The waffle objects passed to the failed function belong to different displays.

           WAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM = 0x12
               The requested action is unsupported on the current system or platform, but is
               otherwise valid.

               For example, attempting to choose a waffle_config whose API is OpenGL ES1 on a
               system that doesn't OpenGL ES1 will produce this error.

           WAFFLE_ERROR_BUILT_WITHOUT_SUPPORT = 0x13
               Waffle was built without support for the requested action.

               For example, if waffle was built without support for GBM, then calling
               waffle_init() with attribute WAFFLE_PLATFORM=WAFFLE_PLATFORM_GBM will produce this
               error.

ISSUES

       Please report bugs or and feature requests to
       https://gitlab.freedesktop.org/mesa/waffle/issues.

SEE ALSO

       waffle(7)

AUTHOR

       Chad Versace <chad.versace@linux.intel.com>
           Maintainer

COPYRIGHT

       Copyright © 2013 Intel

       This manual page is licensed under the Creative Commons Attribution-ShareAlike 3.0 United
       States License (CC BY-SA 3.0). To view a copy of this license, visit
       http://creativecommons.org.license/by-sa/3.0/us.