.. _errors: *************** Error reporting *************** .. highlight:: c :: #include This section defines an API for reporting error conditions. It's loosely modeled on the POSIX ``errno`` mechanism. The standard POSIX approach for reporting errors is to return an integer status code, and to store error codes into the ``errno`` global variable. This approach has a couple of drawbacks. The first is that you --- or really, your C library --- has to ensure that ``errno`` is placed in thread-local storage, so that separate threads have their own error condition variables. The second, and in our mind more important, is that the set of error codes is fixed and platform-dependent. It's difficult to add new error codes to represent application-level error conditions. The libcork error API is a way around this. Like standard POSIX-conforming functions, you return an integer status code from any function that might need to report an error to its caller. The status return code is simple: ``0`` indicates success, ``-1`` indicates failure. When an error occurs, you can use the functions in this section to get more information about the error: an *error code*, and human-readable string description of the error. The POSIX ``errno`` values, while hard to extend, are perfectly well-defined for most platforms; therefore, any ``errno`` value supported by your system's C library is a valid libcork error code. To support new application-specific error codes, an error code can also be the hash of some string describing the error. This “hash of a string” approach makes it easy to define new error codes without needing any centralized mechanism for assigning IDs to the various codes. Moreover, it's very unlikely that a hashed error code will conflict with some existing POSIX ``errno`` value, or with any other hashed error codes. .. note:: We correctly maintain a separate error condition for each thread in the current process. This is all hidden by the functions in this section; it's safe to call them from multiple threads simultaneously. Calling a function that can return an error ------------------------------------------- There are two basic forms for a function that can produce an error. The first is if the function returns a single pointer as its result:: TYPE * my_function(/* parameters */); The second is for any other function:: int my_function(/* parameters */); If an error occurs, the function will return either ``NULL`` or ``-1``, depending on its return type. Success will be indicated by a non-\ ``NULL`` pointer or a ``0``. (More complex return value schemes are possible, if the function needs to signal more than a simple “success” or “failure”; in that case, you'll need to check the function's documentation for details.) If you want to know specifics about the error, there are several functions that you can use to interrogate the current error condition. .. function:: bool cork_error_occurred(void) Returns whether an error has occurred. .. function:: cork_error cork_error_code(void) Returns the error code of the current error condition. If no error has occurred, the result will be :c:macro:`CORK_ERROR_NONE`. .. function:: const char \*cork_error_message(void) Returns the human-readable string description the current error condition. If no error occurred, the result of this function is undefined. You can use the ``cork_error_prefix`` family of functions to add additional context to the beginning of an error message. .. function:: void cork_error_prefix_printf(const char \*format, ...) void cork_error_prefix_string(const char \*string) void cork_error_prefix_vprintf(const char \*format, va_list args) Prepends some additional text to the current error condition. When you're done checking the current error condition, you clear it so that later calls to :c:func:`cork_error_occurred` and friends don't re-report this error. .. function:: void cork_error_clear(void) Clears the current error condition. Writing a function that can return an error ------------------------------------------- When writing a function that might produce an error condition, your function signature should follow one of the two standard patterns described above:: int my_function(/* parameters */); TYPE * my_function(/* parameters */); You should return ``-1`` or ``NULL`` if an error occurs, and ``0`` or a non-\ ``NULL`` pointer if it succeeds. If ``NULL`` is a valid “successful” result of the function, you should use the first form, and define a ``TYPE **`` output parameter to return the actual pointer value. (If you're using the first form, you can use additional return codes if there are other possible results besides a simple “success” and “failure”.) If your function results in an error, you need to fill in the current error condition using the ``cork_error_set`` family of functions: .. function:: void cork_error_set_printf(cork_error ecode, const char \*format, ...) void cork_error_set_string(cork_error ecode, const char \*string) void cork_error_set_vprintf(cork_error ecode, const char \*format, va_list args) Fills in the current error condition. The error condition is defined by the error code *ecode*. The human-readable description is constructed from *string*, or from *format* and any additional parameters, depending on which variant you use. As an example, the :ref:`IP address ` parsing functions fill in :c:macro:`CORK_PARSE_ERROR` error conditions when you try to parse a malformed address:: const char *str = /* the string that's being parsed */; cork_error_set_printf (CORK_PARSE_ERROR, "Invalid IP address: %s", str); If a particular kind of error can be raised in several places throughout your code, it can be useful to define a helper function for filling in the current error condition:: static void cork_ip_address_parse_error(const char *version, const char *str) { cork_error_set_printf (CORK_PARSE_ERROR, "Invalid %s address: %s", version, str); } Error-checking macros --------------------- There can be a lot of repetitive code when calling functions that return error conditions. We provide a collection of helper macros that make it easier to write this code. .. note:: Unlike most libcork modules, these macros are **not** automatically defined when you include the ``libcork/core.h`` header file, since they don't include a ``cork_`` prefix. Because of this, we don't want to pollute your namespace unless you ask for the macros. To do so, you must explicitly include their header file:: #include Additional debugging output ~~~~~~~~~~~~~~~~~~~~~~~~~~~ .. macro:: CORK_PRINT_ERRORS If you define this macro to ``1`` before including :file:`libcork/helpers/errors.h`, then we'll output the current function name, file, and line number, along with the description of the error, to stderr whenever an error is detected by one of the macros described in this section. Returning a default error code ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you follow one of the standard function signature patterns described above, then your function will either return an ``int`` or some pointer type, and errors will be signalled by a return value of ``-1`` or ``NULL``. If so, you can use the macros in this section to automatically return the appropriate error return value if a nested function call returns an error. With these macros, you won't have a chance to inspect the error condition when an error occurs, so you should pass in your own *err* parameter when calling the nested function. (The mnemonic for remembering these macro names is that they all start with ``rXY_``. The ``r`` indicates that they automatically “return”. The second character indicates whether *your* function returns an ``int`` or a pointer. The third character indicates whether the function you're *calling* returns an ``int`` or a pointer.) .. function:: void rie_check(call) Call a function whose return value isn't enough to check for an error, when your function returns an ``int``. We'll use :c:func:`cork_error_occurred` to check for an error. If the nested function call returns an error, we propagate that error on. .. function:: void rii_check(call) Call a function that returns an ``int`` error indicator, when your function also returns an ``int``. If the nested function call returns an error, we propagate that error on. .. function:: void rip_check(call) Call a function that returns a pointer, when your function returns an ``int``. If the nested function call returns an error, we propagate that error on. .. function:: void rpe_check(call) Call a function whose return value isn't enough to check for an error, when your function returns a pointer. We'll use :c:func:`cork_error_occurred` to check for an error. If the nested function call returns an error, we propagate that error on. .. function:: void rpi_check(call) Call a function that returns an ``int`` error indicator, when your function returns a pointer. If the nested function call returns an error, we propagate that error on. .. function:: void rpp_check(call) Call a function that returns a pointer, when your function also returns a pointer. If the nested function call returns an error, we propagate that error on. Returning a non-standard return value ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If your function doesn't have a standard signature, or it uses additional return values besides ``0``, ``1``, ``NULL``, and valid pointers, then you can use the macros in this section to return a custom return value in case of an error. With these macros, you won't have a chance to inspect the error condition when an error occurs, so you should pass in your own *err* parameter when calling the nested function. (The mnemonic for remembering these macro names is that they all start with ``xY_``. The ``x`` doesn't standard for anything in particular. The second character indicates whether the function you're *calling* returns an ``int`` or a pointer. We don't need separate macros for *your* function's return type, since you provide a return value explicitly.) .. function:: void xe_check(retval, call) Call a function whose return value isn't enough to check for an error. If the nested function call raises an error, we propagate that error on, and return *retval* from the current function. .. function:: void xi_check(retval, call) Call a function that returns an ``int`` error indicator. If the nested function call raises an error, we propagate that error on, and return *retval* from the current function. .. function:: void xp_check(retval, call) Call a function that returns a pointer. If the nested function call raises an error, we propagate that error on, and return *retval* from the current function. Post-processing when an error occurs ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ If you need to perform some post-processing when a nested function returns an error, you can use the functions in this section. They will automatically jump to the current scope's ``error`` label whenever an error occurs. (The mnemonic for remembering these macro names is that they all start with ``eY_``. The ``e`` indicates that they'll jump to the ``error`` label. The second character indicates whether the function you're *calling* returns an ``int`` or a pointer. We don't need separate macros for *your* function's return type, since the macros won't automatically return anything.) .. function:: void ei_check(call) Call a function whose return value isn't enough to check for an error. If the nested function call raises an error, we automatically jump to the current scope's ``error`` label. .. function:: void ei_check(call) Call a function that returns an ``int`` error indicator. If the nested function call raises an error, we automatically jump to the current scope's ``error`` label. .. function:: void ep_check(call) Call a function that returns a pointer. If the nested function call raises an error, we automatically jump to the current scope's ``error`` label. Calling POSIX functions ~~~~~~~~~~~~~~~~~~~~~~~ The :c:func:`cork_system_error_set` function automatically translates a POSIX error (specified in the standard ``errno`` variable) into a libcork error condition (which will be reported by :c:func:`cork_error_occurred` and friends). We also define several helper macros for calling a POSIX function and automatically checking its result. :: #include .. note:: For all of these macros, the ``EINTR`` POSIX error is handled specially. This error indicates that a system call was interrupted by a signal, and that the call should be retried. The macros do not translate ``EINTR`` errors into libcork errors; instead, they will retry the ``call`` until the statement succeeds or returns a non-``EINTR`` error. .. function:: void rii_check_posix(call) Call a function that returns an ``int`` error indicator, when your function also returns an ``int``. If the nested function call returns a POSIX error, we translate it into a libcork error and return a libcork error code. .. function:: void rip_check_posix(call) Call a function that returns a pointer, when your function returns an ``int``. If the nested function call returns a POSIX error, we translate it into a libcork error and return a libcork error code. .. function:: void rpi_check_posix(call) Call a function that returns an ``int`` error indicator, when your function returns a pointer. If the nested function call returns a POSIX error, we translate it into a libcork error and return a libcork error code. .. function:: void rpp_check_posix(call) Call a function that returns a pointer, when your function also returns a pointer. If the nested function call returns a POSIX error, we translate it into a libcork error and return a libcork error code. .. function:: void ei_check_posix(call) Call a function that returns an ``int`` error indicator. If the nested function call raises a POSIX error, we translate it into a libcork error and automatically jump to the current scope's ``error`` label. .. function:: void ep_check_posix(call) Call a function that returns a pointer. If the nested function call raises a POSIX error, we translate it into a libcork error and automatically jump to the current scope's ``error`` label. Defining new error codes ------------------------ If none of the built-in error codes suffice for an error condition that you need to report, you'll have to define our own. As mentioned above, each libcork error code is either a predefined POSIX ``errno`` value, or a hash some of string identifying a custom error condition. Typically, you will create a macro in one of your public header files, whose value will be your new custom error code. If this is the case, you can use the macro name itself to create the hash value for the error code. This is what we do for the non-POSIX builtin errors; for instance, the value of the :c:macro:`CORK_PARSE_ERROR` error code macro is the hash of the string ``CORK_PARSE_ERROR``. Given this string, you can produce the error code's hash value using the :ref:`cork-hash ` command that's installed with libcork:: $ cork-hash CORK_PARSE_ERROR 0x95dfd3c8 It's incredibly unlikely that the hash value for your new error code will conflict with any other custom hash-based error codes, or with any predefined POSIX ``errno`` values. With your macro name and hash value ready, defining the new error code is simple:: #define CORK_PARSE_ERROR 0x95dfd3c8 You should also provide a helper macro that makes it easier to report new instances of this error condition:: #define cork_parse_error(...) \ cork_error_set_printf(CORK_PARSE_ERROR, __VA_ARGS__) .. type:: uint32_t cork_error An identifier for a particular error condition. This will either be a predefined POSIX ``errno`` value, or the hash of a unique string describing the error condition. With your error class and code defined, you can fill in error instances using :c:func:`cork_error_set_printf` and friends. Builtin errors -------------- In addition to all of the predefined POSIX ``errno`` values, we also provide error codes for a handful of common error conditions. You should feel free to use these in your libraries and applications, instead of creating custom error codes, if they apply. .. macro:: CORK_ERROR_NONE A special error code that signals that no error occurred. .. macro:: CORK_PARSE_ERROR The provided input violates the rules of the language grammar or file format (or anything else, really) that you're trying to parse. .. function:: void cork_parse_error(const char *format*, ...) .. macro:: CORK_REDEFINED CORK_UNDEFINED Useful when you have a container type that must ensure that there is only one entry for any given key. .. function:: void cork_redefined(const char *format*, ...) void cork_undefined(const char *format*, ...) .. macro:: CORK_UNKNOWN_ERROR Some error occurred, but we don't have any other information about the error. .. function:: void cork_unknown_error(void) The error description will include the name of the current function. We also provide some helper functions for setting these built-in errors: .. function:: void cork_system_error_set(void) void cork_system_error_set_explicit(int err) Fills in the current libcork error condition with information from a POSIX ``errno`` value. The human-readable description of the error will be obtained from the standard ``strerror`` function. With the ``_explicit`` variant, you provide the ``errno`` value directly; for the other variant, we get the error code from the C library's ``errno`` variable. .. function:: void cork_abort(const char \*fmt, ...) Aborts the current program with an error message given by *fmt* and any additional parameters. .. function:: void cork_unreachable(void) Aborts the current program with a message indicating that the code path should be unreachable. This can be useful in the ``default`` clause of a ``switch`` statement if you can ensure that one of the non-``default`` branches will always be selected.