1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_connect - initiate the TLS/SSL handshake with an TLS/SSL server
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_connect(SSL *ssl);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_connect() initiates the TLS/SSL handshake with a server. The communication
   16: channel must already have been set and assigned to the B<ssl> by setting an
   17: underlying B<BIO>.
   18: 
   19: =head1 NOTES
   20: 
   21: The behaviour of SSL_connect() depends on the underlying BIO. 
   22: 
   23: If the underlying BIO is B<blocking>, SSL_connect() will only return once the
   24: handshake has been finished or an error occurred.
   25: 
   26: If the underlying BIO is B<non-blocking>, SSL_connect() will also return
   27: when the underlying BIO could not satisfy the needs of SSL_connect()
   28: to continue the handshake, indicating the problem by the return value -1.
   29: In this case a call to SSL_get_error() with the
   30: return value of SSL_connect() will yield B<SSL_ERROR_WANT_READ> or
   31: B<SSL_ERROR_WANT_WRITE>. The calling process then must repeat the call after
   32: taking appropriate action to satisfy the needs of SSL_connect().
   33: The action depends on the underlying BIO. When using a non-blocking socket,
   34: nothing is to be done, but select() can be used to check for the required
   35: condition. When using a buffering BIO, like a BIO pair, data must be written
   36: into or retrieved out of the BIO before being able to continue.
   37: 
   38: =head1 RETURN VALUES
   39: 
   40: The following return values can occur:
   41: 
   42: =over 4
   43: 
   44: =item 1
   45: 
   46: The TLS/SSL handshake was successfully completed, a TLS/SSL connection has been
   47: established.
   48: 
   49: =item 0
   50: 
   51: The TLS/SSL handshake was not successful but was shut down controlled and
   52: by the specifications of the TLS/SSL protocol. Call SSL_get_error() with the
   53: return value B<ret> to find out the reason.
   54: 
   55: =item E<lt>0
   56: 
   57: The TLS/SSL handshake was not successful, because a fatal error occurred either
   58: at the protocol level or a connection failure occurred. The shutdown was
   59: not clean. It can also occur of action is need to continue the operation
   60: for non-blocking BIOs. Call SSL_get_error() with the return value B<ret>
   61: to find out the reason.
   62: 
   63: =back
   64: 
   65: =head1 SEE ALSO
   66: 
   67: L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_accept(3)|SSL_accept(3)>,
   68: L<SSL_shutdown(3)|SSL_shutdown(3)>, L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>,
   69: L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
   70: L<SSL_do_handshake(3)|SSL_do_handshake(3)>,
   71: L<SSL_CTX_new(3)|SSL_CTX_new(3)>
   72: 
   73: =cut