6.1.3 Common types

All strings that are to provided as input to GnuTLS functions should be in UTF-8 unless otherwise specified. Output strings are also in UTF-8 format unless otherwise specified. When functions take as input passwords, they will normalize them using [RFC7613] rules (since GnuTLS 3.5.7).

When data of a fixed size are provided to GnuTLS functions then the helper structure gnutls_datum_t is often used. Its definition is shown below.

  typedef struct
  {
    unsigned char *data;
    unsigned int size;
  } gnutls_datum_t;

In functions where this structure is a returned type, if the function succeeds, it is expected from the caller to use gnutls_free() to deinitialize the data element after use, unless otherwise specified. If the function fails, the contents of the gnutls_datum_t should be considered undefined and must not be deinitialized.

Other functions that require data for scattered read use a structure similar to struct iovec typically used by readv. It is shown below.

  typedef struct
  {
    void *iov_base;             /* Starting address */
    size_t iov_len;             /* Number of bytes to transfer */
  } giovec_t;