Next: Common types, Previous: General idea, Up: Introduction to the library [Contents][Index]
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).
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.
Next: Common types, Previous: General idea, Up: Introduction to the library [Contents][Index]