Function = gnutls_mac_get_name
  return type: char *

 MACAlgorithm algorithm
    ->  is a MAC algorithm

 Description:
    -> Returns an allocated (with malloc) string that contains the name 
of the specified MAC algorithm.
Function = gnutls_compression_get_name
  return type: char *

 CompressionMethod algorithm
    ->  is a Compression algorithm

 Description:
    -> Returns a localy allocated (with malloc) pointer to a string that contains the name 
of the specified compression algorithm.
Function = gnutls_cipher_get_name
  return type: char *

 BulkCipherAlgorithm algorithm
    ->  is an encryption algorithm

 Description:
    -> Returns a localy allocated (with malloc) pointer to a string that contains the name 
of the specified cipher.
Function = gnutls_kx_get_name
  return type: char *

 KXAlgorithm algorithm
    ->  is a key exchange algorithm

 Description:
    -> Returns a localy allocated (with malloc) pointer to a string that contains the name 
of the specified key exchange algorithm.
Function = gnutls_set_kx_cred
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 KXAlgorithm kx
    ->  is a key exchange algorithm

 void* cred
    ->  is a pointer to a structure.

 Description:
    -> Sets the needed credentials for the specified (in kx) authentication
algorithm. Eg username, password - or public and private keys etc.  
The (void* cred) parameter is a structure that depends on the
specified kx algorithm and on the current state (client or server).
[ In order to minimize memory usage, and share credentials between 
several threads gnutls keeps a pointer to cred, and not the whole cred
structure. Thus you will have to keep the structure allocated until   
you call gnutls_deinit(). ]

For GNUTLS_KX_DH_ANON cred should be NULL in case of a client.
In case of a server it should be DH_ANON_SERVER_CREDENTIALS.   

For GNUTLS_KX_SRP cred should be SRP_CLIENT_CREDENTIALS
in case of a client, and SRP_SERVER_CREDENTIALS, in case
of a server.
Function = gnutls_get_auth_info
  return type: const void*

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> This function must be called after a succesful gnutls_handshake().
Returns a pointer to authentication information.   

In case of GNUTLS_KX_ANON returns a pointer to DH_ANON_AUTH_INFO;

In case of GNUTLS_KX_SRP returns a pointer to structure SRP_AUTH_INFO;
Function = gnutls_check_pending
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> This function checks if there are any data to receive
in the gnutls buffers. Returns the size of that data or 0.
Notice that you may also use select() to check for data in
the TCP connection, instead of this function.
(gnutls leaves some data in the tcp buffer in order for select
to work).
Function = gnutls_set_lowat
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 int num
    ->  is the low water value.

 Description:
    -> Used to set the lowat value in order for select to check
if there are pending data to socket buffer. Used only   
if you have changed the default low water value (default is 1).
Normally you will not need that function.
Function = gnutls_init
  return type: int

 GNUTLS_STATE * state
    ->  is a pointer to a &GNUTLS_STATE structure.

 ConnectionEnd con_end
    ->  is used to indicate if this state is to be used for server or 
client. Can be one of GNUTLS_CLIENT and GNUTLS_SERVER. 

 Description:
    -> This function initializes the current state to null. Every state
must be initialized before use, so internal structures can be allocated.
This function allocates structures which can only be free'd
by calling gnutls_deinit(). Returns zero on success.
Function = gnutls_deinit
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> This function clears all buffers associated with the state.
Function = gnutls_close
  return type: int

 int cd
    ->  is a connection descriptor.

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Terminates the current TLS/SSL connection. If the return value is 0
you may continue using the TCP connection.
Function = gnutls_get_current_cipher
  return type: BulkCipherAlgorithm

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Returns the currently used cipher.
Function = gnutls_get_current_kx
  return type: KXAlgorithm

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Returns the key exchange algorithm used in the last handshake.
Function = gnutls_get_current_mac_algorithm
  return type: MACAlgorithm

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Returns the currently used mac algorithm.
Function = gnutls_get_current_compression_method
  return type: CompressionMethod

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Returns the currently used compression method.
Function = gnutls_get_last_alert
  return type: AlertDescription

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> Returns the last alert number received. This function
should be called if GNUTLS_E_WARNING_ALERT_RECEIVED or
GNUTLS_E_FATAL_ALERT_RECEIVED has been returned by a gnutls function.
The peer may send alerts if he thinks some things were not 
right. Check gnutls.h for the available alert descriptions.
Function = gnutls_send
  return type: ssize_t

 int cd
    ->  is a connection descriptor

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 const void * data
    ->  contains the data to send

 size_t sizeofdata
    ->  is the length of the data

 int flags
    ->  contains the flags to pass to send() function.

 Description:
    -> This function has the same semantics as send() has. The only
difference is that is accepts a GNUTLS state. Currently flags cannot
be anything except 0.
Function = gnutls_recv
  return type: ssize_t

 int cd
    ->  is a connection descriptor

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 void * data
    ->  contains the data to send

 size_t sizeofdata
    ->  is the length of the data

 int flags
    ->  contains the flags to pass to recv() function.

 Description:
    -> This function has the same semantics as recv() has. The only
difference is that is accepts a GNUTLS state. Flags are the flags
passed to recv() and should be used with care in gnutls.  
The only acceptable flag is currently MSG_DONTWAIT. In that case,
if the socket is set to non blocking IO it will return GNUTLS_E_AGAIN,
if there are no data in the socket. 
Function = gnutls_write
  return type: ssize_t

 int cd
    ->  is a connection descriptor

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 const void * data
    ->  contains the data to send

 size_t sizeofdata
    ->  is the length of the data

 Description:
    -> This function has the same semantics as write() has. The only
difference is that is accepts a GNUTLS state.
Function = gnutls_read
  return type: ssize_t

 int cd
    ->  is a connection descriptor

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 void * data
    ->  contains the data to send

 size_t sizeofdata
    ->  is the length of the data

 Description:
    -> This function has the same semantics as read() has. The only
difference is that is accepts a GNUTLS state. 
Function = gnutls_set_cache_expiration
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 int seconds
    ->  is the number of seconds.

 Description:
    -> Sets the expiration time for resumed sessions. The default is 3600 (one hour)
at the time writing this.
Function = gnutls_set_db_name
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 char* filename
    ->  is the filename for the database

 Description:
    -> Sets the name of the (gdbm) database to be used to keep
the sessions to be resumed. This function also creates the database
- if it does not exist - and opens it for reading.
Function = gnutls_clean_db
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 Description:
    -> This function Deletes all expired records in the db. This db may become huge
if this function is not called.
Function = gnutls_is_fatal_error
  return type: int

 int error
    ->  is an error returned by a gnutls function. Error is always a negative value.

 Description:
    -> If a function returns a negative value you may feed that value
to this function to see if it is fatal. Returns 1 for a fatal 
error 0 otherwise. However you may want to check the
error code manualy, since some non-fatal errors to the protocol
may be fatal for you (your program).
Function = gnutls_perror
  return type: void

 int error
    ->  is an error returned by a gnutls function. Error is always a negative value.

 Description:
    -> This function is like perror(). However it accepts an error returned by a gnutls
function. 
Function = gnutls_strerror
  return type: char*

 int error
    ->  is an error returned by a gnutls function. Error is always a negative value.

 Description:
    -> This function is like strerror(). However it accepts an error returned by a gnutls
function. gnutls_strerror() returns a malloc'ed value thus 
it should be free'd.
Function = gnutls_send_hello_request
  return type: int

 int cd
    ->  is a connection descriptor, as returned by socket().

 GNUTLS_STATE state
    ->  is a a &GNUTLS_STATE structure.

 Description:
    -> This function will renegotiate security parameters with the
client. This should only be called in case of a server.
If the client does not wish to renegotiate parameters he
will reply with an alert message, thus the return code will be
GNUTLS_E_WARNING_ALERT_RECEIVED and the alert will be
GNUTLS_NO_RENEGOTIATION.
Function = gnutls_handshake
  return type: int

 int cd
    ->  is a connection descriptor, as returned by socket().

 GNUTLS_STATE state
    ->  is a a &GNUTLS_STATE structure.

 Description:
    -> This function does the handshake of the TLS/SSL protocol,
and initializes the TLS connection. Here the identity of the peer
is checked automatically.
This function will fail if any problem is encountered,
and the connection should be terminated.
Function = gnutls_handshake_begin
  return type: int

 int cd
    ->  is a connection descriptor, as returned by socket().

 GNUTLS_STATE state
    ->  is a a &GNUTLS_STATE structure.

 Description:
    -> This function initiates the handshake of the TLS/SSL protocol.
Here we will receive - if requested and supported by the ciphersuite -
the peer's certificate. 

This function will fail if any problem in the handshake is encountered.   
However this failure will not be fatal. However you may choose to
continue the handshake - eg. even if the certificate cannot
be verified- by calling gnutls_handshake_finish().
Function = gnutls_handshake_finish
  return type: int

 int cd
    ->  is a connection descriptor, as returned by socket().

 GNUTLS_STATE state
    ->  is a a &GNUTLS_STATE structure.

 Description:
    -> This function does the final stuff of the handshake protocol.
You should call it only if you used gnutls_handshake_begin() and
you have somehow verified the identity of the peer.
This function will fail if any problem is encountered.
Function = gnutls_set_cipher_priority
  return type: void

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.
@...: is a 0 terminated list of BulkCipherAlgorithm elements.

  ...
    -> -- undescribed --
 Description:
    -> Sets the priority on the ciphers supported by gnutls.
Priority is higher for ciphers specified before others.
After specifying the ciphers you want, you should add 0.
Note that the priority is set on the client. The server does
not use the algorithm's priority except for disabling
algorithms that were not specified.
Function = gnutls_set_kx_priority
  return type: void

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.
@...: is a 0 terminated list of KXAlgorithm elements.

  ...
    -> -- undescribed --
 Description:
    -> Sets the priority on the key exchange algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 0.
Note that the priority is set on the client. The server does
not use the algorithm's priority except for disabling
algorithms that were not specified.
Function = gnutls_set_mac_priority
  return type: void

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.
@...: is a 0 terminated list of MACAlgorithm elements.

  ...
    -> -- undescribed --
 Description:
    -> Sets the priority on the mac algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 0.
Note that the priority is set on the client. The server does
not use the algorithm's priority except for disabling
algorithms that were not specified.
Function = gnutls_set_compression_priority
  return type: void

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.
@...: is a 0 terminated list of CompressionMethod elements.

  ...
    -> -- undescribed --
 Description:
    -> Sets the priority on the compression algorithms supported by gnutls.
Priority is higher for algorithms specified before others.
After specifying the algorithms you want, you should add 0.
Note that the priority is set on the client. The server does
not use the algorithm's priority except for disabling
algorithms that were not specified.
Function = gnutls_get_current_session
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 opaque* session
    ->  is a pointer to space to hold the session.

 int * session_size
    ->  is the session's size, or it will be set by the function.

 Description:
    -> Returns all session parameters - in order to support resuming.
The client should call this - and keep the returned session - if he wants to
resume that current version later by calling gnutls_set_current_session()
This function must be called after a successful handshake.

Resuming sessions is really useful and speedups connections after a succesful one.
Function = gnutls_get_current_session_id
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 void* session
    ->  is a pointer to space to hold the session id.

 int * session_size
    ->  is the session id's size, or it will be set by the function.

 Description:
    -> Returns the current session id. This can be used if you want to check if
the next session you tried to resume was actually resumed.
(resumed sessions have the same sessionID with the first session)

Session id is some data set by the server, that identify the current session. 
In TLS 1.0 session id should not be more than 32 bytes.
Function = gnutls_set_current_session
  return type: int

 GNUTLS_STATE state
    ->  is a &GNUTLS_STATE structure.

 opaque* session
    ->  is a pointer to space to hold the session.

 int session_size
    ->  is the session's size

 Description:
    -> Sets all session parameters - in order to support resuming
session must be the one returned by gnutls_get_current_session();
This function should be called before gnutls_handshake_begin() or gnutls_handshake().
Keep in mind that session resuming is advisory. The server may
choose not to resume the session, thus a full handshake will be
performed.
