.\" DO NOT MODIFY THIS FILE!  It was generated by gdoc.
.TH "gnutls_handshake" 3 "3.5.8" "gnutls" "gnutls"
.SH NAME
gnutls_handshake \- API function
.SH SYNOPSIS
.B #include <gnutls/gnutls.h>
.sp
.BI "int gnutls_handshake(gnutls_session_t " session ");"
.SH ARGUMENTS
.IP "gnutls_session_t session" 12
is a \fBgnutls_session_t\fP type.
.SH "DESCRIPTION"
This function does the handshake of the TLS/SSL protocol, and
initializes the TLS connection.

This function will fail if any problem is encountered, and will
return a negative error code. In case of a client, if the client
has asked to resume a session, but the server couldn't, then a
full handshake will be performed.

The non\-fatal errors expected by this function are:
\fBGNUTLS_E_INTERRUPTED\fP, \fBGNUTLS_E_AGAIN\fP, 
\fBGNUTLS_E_WARNING_ALERT_RECEIVED\fP, and \fBGNUTLS_E_GOT_APPLICATION_DATA\fP,
the latter only in a case of rehandshake.

The former two interrupt the handshake procedure due to the lower
layer being interrupted, and the latter because of an alert that
may be sent by a server (it is always a good idea to check any
received alerts). On these errors call this function again, until it
returns 0; cf.  \fBgnutls_record_get_direction()\fP and
\fBgnutls_error_is_fatal()\fP. In DTLS sessions the non\-fatal error
\fBGNUTLS_E_LARGE_PACKET\fP is also possible, and indicates that
the MTU should be adjusted.

If this function is called by a server after a rehandshake request
then \fBGNUTLS_E_GOT_APPLICATION_DATA\fP or
\fBGNUTLS_E_WARNING_ALERT_RECEIVED\fP may be returned.  Note that these
are non fatal errors, only in the specific case of a rehandshake.
Their meaning is that the client rejected the rehandshake request or
in the case of \fBGNUTLS_E_GOT_APPLICATION_DATA\fP it could also mean that
some data were pending. A client may receive that error code if
it initiates the handshake and the server doesn't agreed.
.SH "RETURNS"
\fBGNUTLS_E_SUCCESS\fP on success, otherwise a negative error code.
.SH "REPORTING BUGS"
Report bugs to <bugs@gnutls.org>.
.br
Home page: http://www.gnutls.org

.SH COPYRIGHT
Copyright \(co 2001-2017 Free Software Foundation, Inc., and others.
.br
Copying and distribution of this file, with or without modification,
are permitted in any medium without royalty provided the copyright
notice and this notice are preserved.
.SH "SEE ALSO"
The full documentation for
.B gnutls
is maintained as a Texinfo manual.
If the /usr/share/doc/gnutls/
directory does not contain the HTML form visit
.B
.IP http://www.gnutls.org/manual/
.PP