1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_write - write bytes to a TLS/SSL connection.
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  int SSL_write(SSL *ssl, const void *buf, int num);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
   16: B<ssl> connection.
   17: 
   18: =head1 NOTES
   19: 
   20: If necessary, SSL_write() will negotiate a TLS/SSL session, if
   21: not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
   22: L<SSL_accept(3)|SSL_accept(3)>. If the
   23: peer requests a re-negotiation, it will be performed transparently during
   24: the SSL_write() operation. The behaviour of SSL_write() depends on the
   25: underlying BIO. 
   26: 
   27: For the transparent negotiation to succeed, the B<ssl> must have been
   28: initialized to client or server mode. This is being done by calling
   29: L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
   30: before the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function.
   31: 
   32: If the underlying BIO is B<blocking>, SSL_write() will only return, once the
   33: write operation has been finished or an error occurred, except when a
   34: renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. 
   35: This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
   36: L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
   37: 
   38: If the underlying BIO is B<non-blocking>, SSL_write() will also return,
   39: when the underlying BIO could not satisfy the needs of SSL_write()
   40: to continue the operation. In this case a call to
   41: L<SSL_get_error(3)|SSL_get_error(3)> with the
   42: return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
   43: B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
   44: call to SSL_write() can also cause read operations! The calling process
   45: then must repeat the call after taking appropriate action to satisfy the
   46: needs of SSL_write(). The action depends on the underlying BIO. When using a
   47: non-blocking socket, nothing is to be done, but select() can be used to check
   48: for the required condition. When using a buffering BIO, like a BIO pair, data
   49: must be written into or retrieved out of the BIO before being able to continue.
   50: 
   51: SSL_write() will only return with success, when the complete contents
   52: of B<buf> of length B<num> has been written. This default behaviour
   53: can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
   54: L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set,
   55: SSL_write() will also return with success, when a partial write has been
   56: successfully completed. In this case the SSL_write() operation is considered
   57: completed. The bytes are sent and a new SSL_write() operation with a new
   58: buffer (with the already sent bytes removed) must be started.
   59: A partial write is performed with the size of a message block, which is
   60: 16kB for SSLv3/TLSv1.
   61: 
   62: =head1 WARNING
   63: 
   64: When an SSL_write() operation has to be repeated because of
   65: B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
   66: with the same arguments.
   67: 
   68: When calling SSL_write() with num=0 bytes to be sent the behaviour is
   69: undefined.
   70: 
   71: =head1 RETURN VALUES
   72: 
   73: The following return values can occur:
   74: 
   75: =over 4
   76: 
   77: =item E<gt>0
   78: 
   79: The write operation was successful, the return value is the number of
   80: bytes actually written to the TLS/SSL connection.
   81: 
   82: =item 0
   83: 
   84: The write operation was not successful. Probably the underlying connection
   85: was closed. Call SSL_get_error() with the return value B<ret> to find out,
   86: whether an error occurred or the connection was shut down cleanly
   87: (SSL_ERROR_ZERO_RETURN).
   88: 
   89: SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
   90: only be detected, whether the underlying connection was closed. It cannot
   91: be checked, why the closure happened.
   92: 
   93: =item E<lt>0
   94: 
   95: The write operation was not successful, because either an error occurred
   96: or action must be taken by the calling process. Call SSL_get_error() with the
   97: return value B<ret> to find out the reason.
   98: 
   99: =back
  100: 
  101: =head1 SEE ALSO
  102: 
  103: L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>,
  104: L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
  105: L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
  106: L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
  107: L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
  108: 
  109: =cut