Use GError to report a recoverable runtime failure—such as a missing file or invalid input—to the function’s caller, so the caller can inspect the cause and decide what to do. The function reports the failure through a GError ** parameter and still follows its failure return path; g_error() is different: it is fatal and is intended for programming errors, not recoverable failures.
What GError represents
A GError is structured error information passed across an API boundary. It contains a domain, a code, and a message. The domain and code let callers classify the failure; the message gives more detail. That makes an error more useful than a string printed to a log: the caller can make a decision based on the error rather than merely display or record it.
As an Amazon Associate I earn from qualifying purchases.
GLib’s convention is for a function that can fail to accept a GError **error parameter, usually as its last regular argument. If the operation fails, the function sets an error when the caller supplied a location for one, then returns its failure result. The caller checks the result and handles the error. See the GLib Error Reporting guide and the GError API reference.
PC Slower Than It Used to Be?
A free scan shows the junk files, broken settings and background clutter dragging Windows down - then fixes them in one click.Free scan · Windows 10 & 11Crashes, No Sound, or Screen Glitches?
Random freezes, missing sound and display glitches usually trace back to one bad driver. Find and replace yours safely.Free scan · under a minuteHow to handle a GError
- Initialize the error pointer to
NULL. A caller-providedGError *must be clear before passing its address to a function. - Call the function and check its failure result. Follow the function’s documented return convention. An error indicates that the operation failed; do not treat it as a warning while continuing as though the operation succeeded.
- Inspect the error when appropriate. Use its domain and code to select the response. The message may help explain the details, but it may be too technical for a user-facing message.
- Clear or propagate the error. If this code handles the failure, call
g_clear_error()to free the error and set the pointer toNULL. If a higher-level caller should decide what to do, propagate it using the documented error helpers.
For example, g_file_get_contents() can fail because a file cannot be read. Its error message can explain the underlying problem, but a user interface may need a more useful message tailored to the action the person was trying to perform. Match the domain and code when the program needs to distinguish causes, and present an appropriate message in the interface rather than assuming the low-level message is suitable. If displaying an error through GTK, the message must be valid UTF-8; filenames may need conversion from the platform’s filename encoding. These conventions and caveats are documented in the GLib Error Reporting guide.
#1 Best Overall
Rules for functions that set errors
- Do not overwrite an existing error. GLib’s documentation says, “Error pileups are always a bug.” If code can continue after handling an error, clear it before another operation that may set one.
- A NULL error location does not mean success. A caller may pass
NULLto decline error details. In that case,g_set_error()does nothing, but the function must still follow its failure path and return failure. - Do not rely on output parameters after failure. When an operation fails, its output parameters may not contain defined values. Use them only as the API documentation permits.
- Keep reporting separate from logging. Setting a
GErrorcommunicates structured information to the caller. Printing or logging that information is a separate choice.
GError versus g_error()
| Choice | Intended use | What happens next | Information available to caller |
|---|---|---|---|
GError |
Recoverable runtime failure, such as missing input or a file that cannot be read | The function returns its failure result; the caller can handle the failure | Structured domain, code, and message |
g_error() |
Fatal programming error | Terminates the program rather than returning control for recovery | Not a recoverable error object for caller inspection |
The GNOME g_error() API documentation states, “This is not intended for end user error reporting.” Use GError when a caller needs to inspect a recoverable failure and choose a response. Programming mistakes should be fixed or handled with appropriate programming-error facilities, such as assertions, precondition checks, or warnings; they should not be disguised as runtime failures that callers are expected to recover from.
Scope and GLib version considerations
Not every GLib function uses GError. Some APIs do not report errors this way, and some situations use numeric error codes. Follow the contract of the specific function you are calling rather than assuming an error parameter exists.
For custom error types, G_DEFINE_EXTENDED_ERROR() is available since GLib 2.68, according to the GLib Error Reporting guide. The current g_error() API reference identifies its library version as 2.90.0; documentation version labels can change as GLib documentation is updated.
Recommended Free Tools
Quick Recap
Best Value
Product prices and availability are accurate as of the date/time indicated and are subject to change. Any price and availability information displayed on Amazon at the time of purchase will apply.
