'\" t .\" Title: waffle_init .\" Author: Chad Versace .\" Generator: DocBook XSL Stylesheets vsnapshot .\" Date: 03/25/2021 .\" Manual: Waffle Manual .\" Source: waffle .\" Language: English .\" .TH "WAFFLE_INIT" "3" "03/25/2021" "waffle" "Waffle Manual" .\" ----------------------------------------------------------------- .\" * Define some portability stuff .\" ----------------------------------------------------------------- .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .\" http://bugs.debian.org/507673 .\" http://lists.gnu.org/archive/html/groff/2009-02/msg00013.html .\" ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ .ie \n(.g .ds Aq \(aq .el .ds Aq ' .\" ----------------------------------------------------------------- .\" * set default formatting .\" ----------------------------------------------------------------- .\" disable hyphenation .nh .\" disable justification (adjust text to left margin only) .ad l .\" ----------------------------------------------------------------- .\" * MAIN CONTENT STARTS HERE * .\" ----------------------------------------------------------------- .SH "NAME" waffle_error, waffle_error_get_info, waffle_error_get_code, waffle_error_to_string \- Thread\-local error state .SH "SYNOPSIS" .sp .ft B .nf #include enum waffle_error {\&.\&.\&.}; struct waffle_error_info { enum waffle_error code; const char *message; size_t message_length; }; .fi .ft .HP \w'const\ struct\ waffle_error_info*\ waffle_error_get_info('u .BI "const struct waffle_error_info* waffle_error_get_info(void);" .HP \w'enum\ waffle_error\ waffle_error_get_code('u .BI "enum waffle_error waffle_error_get_code(void);" .HP \w'const\ char*\ waffle_error_to_string('u .BI "const char* waffle_error_to_string(enum\ waffle_error" "e" ");" .SH "DESCRIPTION" .PP Waffle functions usually return either a \fBbool\fR, 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\&. .PP The only functions that do not alter waffle\*(Aqs 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 \fBwaffle_init\fR(3) .PP \fBstruct waffle_error_info\fR .RS 4 This struct contains the user\-visible portion of waffle\*(Aqs thread\-local error state\&. .sp \fIcode\fR may be any token from \fBenum waffle_error\fR\&. .sp \fImessage\fR often contains a descriptive message about the error\&. It is never null, though it may be the empty string\&. .sp \fImessage_length\fR is the length of \fImessage\fR according to \fBstrlen\fR(3)\&. .RE .PP \fBwaffle_error_to_string()\fR .RS 4 Convert a \fBwaffle_error\fR token to a string\&. For example, convert \fBWAFFLE_ERROR_UNKNOWN\fR to "WAFFLE_ERROR_UNKNOWN"\&. Return null if the token is not a valid error token\&. .sp This function always sets the error code to \fBWAFFLE_ERROR_NONE\fR\&. .RE .PP \fBwaffle_error_get_info()\fR .RS 4 Get information about the current thread\*(Aqs error state\&. .sp This function never returns null\&. The returned pointer becomes invalid when the thread\-local error state changes\&. .sp This function does not alter waffle\*(Aqs error state\&. .RE .PP \fBwaffle_error_get_code()\fR .RS 4 Get the current thread\*(Aqs error code\&. Calling this function is equivalent to obtaining the error code with waffle_error_get_info()\->code\&. .sp This function does not alter waffle\*(Aqs error state\&. .RE .PP \fBenum waffle_error\fR .RS 4 For reference, below is the complete list of waffle\*(Aqs error codes\&. .PP \fBWAFFLE_NO_ERROR\fR = 0x00 .RS 4 The function succeeded\&. .RE .PP \fBWAFFLE_ERROR_FATAL\fR = 0x01 .RS 4 Waffle encountered a fatal error\&. All future waffle calls result in undefined behavior\&. .RE .PP \fBWAFFLE_ERROR_UNKNOWN\fR = 0x02 .RS 4 Waffle encountered an error for which it lacks an error code\&. This is usually produced when an underlying native call, such as \fBXOpenDisplay\fR(3), fails for an unknown reason\&. .RE .PP \fBWAFFLE_ERROR_INTERNAL\fR = 0x03 .RS 4 You found a bug in waffle\&. Please report it\&. The error message, obtained by \fBwaffle_error_get_info()\fR, should contain a description of the bug\&. .RE .PP \fBWAFFLE_ERROR_BAD_ALLOC\fR = 0x04 .RS 4 Waffle failed to allocate memory\&. .RE .PP \fBWAFFLE_ERROR_NOT_INITIALIZED\fR = 0x05 .RS 4 The failed function requires waffle to be initialized with \fBwaffle_init\fR(3)\&. .RE .PP \fBWAFFLE_ERROR_ALREADY_INITIALIZED\fR = 0x06 .RS 4 If waffle has already been initialized by a successful call to \fBwaffle_init\fR(3), then subsequent calls to \fBwaffle_init()\fR produce this error\&. .RE .PP \fBWAFFLE_ERROR_BAD_ATTRIBUTE\fR = 0x08 .RS 4 An unrecognized attribute name or attribute value was passed in an attribute list\&. .RE .PP \fBWAFFLE_ERROR_BAD_PARAMETER\fR = 0x10 .RS 4 The failed function was passed an invalid argument\&. .RE .PP \fBWAFFLE_ERROR_BAD_DISPLAY_MATCH\fR = 0x11 .RS 4 The waffle objects passed to the failed function belong to different displays\&. .RE .PP \fBWAFFLE_ERROR_UNSUPPORTED_ON_PLATFORM\fR = 0x12 .RS 4 The requested action is unsupported on the current system or platform, but is otherwise valid\&. .sp For example, attempting to choose a \fBwaffle_config\fR whose API is OpenGL ES1 on a system that doesn\*(Aqt OpenGL ES1 will produce this error\&. .RE .PP \fBWAFFLE_ERROR_BUILT_WITHOUT_SUPPORT\fR = 0x13 .RS 4 Waffle was built without support for the requested action\&. .sp 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\&. .RE .sp .RE .SH "ISSUES" .PP Please report bugs or and feature requests to \m[blue]\fB\%https://gitlab.freedesktop.org/mesa/waffle/issues\fR\m[]\&. .SH "SEE ALSO" .PP \fBwaffle\fR(7) .SH "AUTHOR" .PP \fBChad Versace\fR <\&chad\&.versace@linux\&.intel\&.com\&> .RS 4 Maintainer .RE .SH "COPYRIGHT" .br Copyright \(co 2013 Intel .br .PP 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 \m[blue]\fB\%http://creativecommons.org.license/by-sa/3.0/us\fR\m[]\&. .sp