SSL_write(3)SSL_write(3)NAMESSL_write - Write bytes to a TLS/SSL connection.
SYNOPSIS
#include <openssl/ssl.h>
int SSL_write(
SSL *ssl,
const void *buf,
int num );
DESCRIPTION
The SSL_write() function writes num bytes from the buffer buf into the
specified ssl connection.
NOTES
If necessary, the SSL_write() function will negotiate a TLS/SSL ses‐
sion, if not already explicitly performed by SSL_connect() or
SSL_accept(). If the peer requests a renegotiation, it will be per‐
formed transparently during the SSL_write() operation. The behavior of
SSL_write() depends on the underlying BIO.
For the transparent negotiation to succeed, the ssl must have been ini‐
tialized to client or server mode. This is done by calling the
SSL_set_connect_state() or SSL_set_accept_state() functions before the
first call to an SSL_read() or SSL_write() function.
If the underlying BIO is blocking, SSL_write() will only return once
the write operation finishes or an error occurs, except when a renego‐
tiation take place, in which case an SSL_ERROR_WANT_READ might occur.
This behavior can be controlled with the SSL_MODE_AUTO_RETRY flag of
the SSL_CTX_set_mode() function.
If the underlying BIO is non-blocking, SSL_write() will also return,
when the underlying BIO could not satisfy the needs of SSL_write() to
continue the operation. In this case a call to SSL_get_error() with the
return value of SSL_write() will yield SSL_ERROR_WANT_READ or
SSL_ERROR_WANT_WRITE. As at any time a renegotiation is possible, a
call to SSL_write() can also cause read operations. The calling process
then must repeat the call after taking appropriate action to satisfy
the needs of SSL_write(). The action depends on the underlying BIO.
When using a non-blocking socket, nothing is to be done, but select()
can be used to check for the required condition. When using a buffering
BIO, like a BIO pair, data must be written into or retrieved out of the
BIO before being able to continue.
The SSL_write() function will only return with success when the com‐
plete contents of buf of length num has been written. This default
behavior can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option
of SSL_CTX_set_mode(). When this flag is set, SSL_write() will also
return with success when a partial write successfully completes. In
this case, the SSL_write() operation is considered complete. The bytes
are sent and a new SSL_write() operation with a new buffer (with the
previously sent bytes removed) must be started. A partial write is per‐
formed with the size of a message block, which is 16kB for SSLv3/TLSv1.
RESTRICTIONS
When an SSL_write() operation has to be repeated because of
SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE, it must be repeated with
the same arguments.
WARNINGS
When calling SSL_write() with num= 0 bytes the behavior is undefined.
RETURN VALUES
The following return values can occur: The write operation was success‐
ful, the return value is the number of bytes actually written to the
TLS/SSL connection. The write operation was not successful. The under‐
lying connection was probably closed. Call SSL_get_error() with the
return value ret to determine if an error occurred or the connection
was shut down cleanly (SSL_ERROR_ZERO_RETURN). SSLv2 (deprecated) does
not support a shutdown alert protocol, so it can only be detected if an
underlying connection was closed. It cannot check why the closure hap‐
pened. The write operation was not successful, because either an error
occurred or action must be taken by the calling process. Call
SSL_get_error() with the return value ret to find the reason.
SEE ALSO
Functions: SSL_get_error(3), SSL_read(3), SSL_CTX_set_mode(3),
SSL_CTX_new(3), SSL_connect(3), SSL_accept(3)SSL_set_connect_state(3),
ssl(3), bio(3)SSL_write(3)
