WAFFLE_INIT(3)

📦
version 1.8.3 · 7 versions
, in ubuntu stonking

💖 WAFFLE_INIT(3) — the Waffle Manual, bestie edition 💖

okay so. welcome to the Waffle Manual, section 3. sit down, grab a strawberry 🍓, because we're talking about thread-local error state and honestly? it's giving essential. this is the page for waffle_error, waffle_error_get_info, waffle_error_get_code, and waffle_error_to_string — your little support group when a Waffle call goes sideways. no cap.

✨ 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);

(yes, enum waffle_errore up there is exactly what the page says. we are simply relaying it. 💅)

👑 DESCRIPTION 👑

so the whole vibe of Waffle functions is: they usually return either a bool, where false means failure 💀, or a pointer, where null means failure. but like, a return value alone is not the tea — because most functions also clear and then set some thread-local error state. clear, then set. every single time. it's a whole ritual. ✨

now, the only functions that do NOT alter Waffle's error state are the ones listed right here, and they're explicitly documented as such, so this is your safe little bubble. 🫧 and here's the slay: all functions listed here can be called before Waffle has been successfully initialized with waffle_init(3). yes bestie, before init. iconic.

🌈 struct waffle_error_info

this struct contains the user-visible portion of Waffle's thread-local error state. tres important.

  • 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. (silent but present. we love a mysterious queen. 🙈)
  • 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. always. no exceptions.

🧚 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 — so like, screenshot it mentally while it's still valid, because it will not wait for you. 😭
  • 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. same energy, less typing. ✨

this function does not alter Waffle's error state.

⭐ enum waffle_error

for reference, below is the complete list of Waffle's error codes. the whole roster. the lineup. 🫶

  • WAFFLE_NO_ERROR = 0x00 — the function succeeded. the best possible outcome. ate and left no crumbs. 💅
  • WAFFLE_ERROR_FATAL = 0x01 — Waffle encountered a fatal error. All future waffle calls result in undefined behavior. genuinely do not keep going after this one, this is the part where you stop. 💀
  • 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. mystery error, no explanation, rude of it. 🙈
  • 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. main character detective moment 🕵️‍♀️
  • 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). bestie you forgot the prerequisite. 🌸
  • 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. one init per era, that's the rule. ✋
  • 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. wrong input, wrong vibe. 😬
  • WAFFLE_ERROR_BAD_DISPLAY_MATCH = 0x11 — the Waffle objects passed to the failed function belong to different displays. they're not in the same group chat, they can't hang out. 💔
  • 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. it's not your fault, it's the platform's fault. 🫶
  • 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. the build said no. 💅

🐛 ISSUES 🐛

please report bugs or and feature requests to https://gitlab.freedesktop.org/mesa/waffle/issues. come through, we're listening. 🔥

🌸 SEE ALSO 🌸

💖 AUTHOR 💖

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

  • Former maintainer

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.

and that's the whole page, bestie!! 💖 no cap, you now officially understand thread-local error state better than like 90% of people who call themselves developers. this was waffle 🧇, dated 07/06/2026, and it lives in section WAFFLE_INIT(3) forever and always. go forth and check your error codes before you check anything else. slay ✨🦋👑

📦 where this page comes from