6.1.2 Error handling

There two types of GnuTLS functions. The first type returns a boolean value, true (non-zero) or false (zero) value; these functions are defined to return an unsigned integer type. The other type returns a signed integer type with zero (or a positive number) indicating success and a negative value indicating failure. For the latter type it is recommended to check for errors as following.

    ret = gnutls_function();
    if (ret < 0) {
        return -1;
    }

The above example checks for a failure condition rather than for explicit success (e.g., equality to zero). That has the advantage that future extensions of the API can be extended to provide additional information via positive returned values (see for example gnutls_certificate_set_x509_key_file).

In GnuTLS, many objects are represented as opaque types that are initialized by passing an address to storage of that type to a pointer parameter of a function name gnutls_obj_init, and which have a counterpart function gnutls_obj_deinit. It is safe, but not mandatory, to pre-initialize the opaque storage to contain all zeroes (such as by using calloc() or memset()). If the initializer succeeds, the storage must be passed to the counterpart deinitializer when the object is no longer in use to avoid memory leaks. As of version 3.8.0, if the initializer function fails, it is safe, but not mandatory, to call the counterpart deinitializer, regardless of whether the storage was pre-initialized. However, this was not guaranteed in earlier versions; for maximum portability to older library versions, callers should either pre-initialize the storage to zero before initialization or refrain from calling the deinitializer if the initializer fails.

For certain operations such as TLS handshake and TLS packet receive there is the notion of fatal and non-fatal error codes. Fatal errors terminate the TLS session immediately and further sends and receives will be disallowed. Such an example is GNUTLS_E_DECRYPTION_FAILED. Non-fatal errors may warn about something, i.e., a warning alert was received, or indicate the some action has to be taken. This is the case with the error code GNUTLS_E_REHANDSHAKE returned by gnutls_record_recv. This error code indicates that the server requests a re-handshake. The client may ignore this request, or may reply with an alert. You can test if an error code is a fatal one by using the gnutls_error_is_fatal. All errors can be converted to a descriptive string using gnutls_strerror.

If any non fatal errors, that require an action, are to be returned by a function, these error codes will be documented in the function’s reference. For example the error codes GNUTLS_E_WARNING_ALERT_RECEIVED and GNUTLS_E_FATAL_ALERT_RECEIVED that may returned when receiving data, should be handled by notifying the user of the alert (as explained in Handling alerts). See Error codes, for a description of the available error codes.