SSL_write.pod revision 100936
168651Skris=pod 268651Skris 368651Skris=head1 NAME 468651Skris 572613SkrisSSL_write - write bytes to a TLS/SSL connection. 668651Skris 768651Skris=head1 SYNOPSIS 868651Skris 968651Skris #include <openssl/ssl.h> 1068651Skris 1176866Skris int SSL_write(SSL *ssl, const void *buf, int num); 1268651Skris 1368651Skris=head1 DESCRIPTION 1468651Skris 1568651SkrisSSL_write() writes B<num> bytes from the buffer B<buf> into the specified 1668651SkrisB<ssl> connection. 1768651Skris 1868651Skris=head1 NOTES 1968651Skris 2068651SkrisIf necessary, SSL_write() will negotiate a TLS/SSL session, if 2176866Skrisnot already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or 2276866SkrisL<SSL_accept(3)|SSL_accept(3)>. If the 2368651Skrispeer requests a re-negotiation, it will be performed transparently during 2468651Skristhe SSL_write() operation. The behaviour of SSL_write() depends on the 2568651Skrisunderlying BIO. 2668651Skris 2776866SkrisFor the transparent negotiation to succeed, the B<ssl> must have been 2889837Skrisinitialized to client or server mode. This is being done by calling 2976866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() 3089837Skrisbefore the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function. 3176866Skris 3268651SkrisIf the underlying BIO is B<blocking>, SSL_write() will only return, once the 3376866Skriswrite operation has been finished or an error occurred, except when a 3476866Skrisrenegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. 3576866SkrisThis behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the 3676866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. 3768651Skris 3868651SkrisIf the underlying BIO is B<non-blocking>, SSL_write() will also return, 3968651Skriswhen the underlying BIO could not satisfy the needs of SSL_write() 4076866Skristo continue the operation. In this case a call to 4176866SkrisL<SSL_get_error(3)|SSL_get_error(3)> with the 4268651Skrisreturn value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or 4368651SkrisB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 4472613Skriscall to SSL_write() can also cause read operations! The calling process 4568651Skristhen must repeat the call after taking appropriate action to satisfy the 4668651Skrisneeds of SSL_write(). The action depends on the underlying BIO. When using a 4768651Skrisnon-blocking socket, nothing is to be done, but select() can be used to check 4868651Skrisfor the required condition. When using a buffering BIO, like a BIO pair, data 4968651Skrismust be written into or retrieved out of the BIO before being able to continue. 5068651Skris 5179998SkrisSSL_write() will only return with success, when the complete contents 5279998Skrisof B<buf> of length B<num> has been written. This default behaviour 5379998Skriscan be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of 5479998SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set, 5579998SkrisSSL_write() will also return with success, when a partial write has been 5679998Skrissuccessfully completed. In this case the SSL_write() operation is considered 5779998Skriscompleted. The bytes are sent and a new SSL_write() operation with a new 5879998Skrisbuffer (with the already sent bytes removed) must be started. 5979998SkrisA partial write is performed with the size of a message block, which is 6079998Skris16kB for SSLv3/TLSv1. 6179998Skris 6268651Skris=head1 WARNING 6368651Skris 6468651SkrisWhen an SSL_write() operation has to be repeated because of 6568651SkrisB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 6668651Skriswith the same arguments. 6768651Skris 68100936SnectarWhen calling SSL_write() with num=0 bytes to be sent the behaviour is 69100936Snectarundefined. 70100936Snectar 7168651Skris=head1 RETURN VALUES 7268651Skris 7368651SkrisThe following return values can occur: 7468651Skris 7568651Skris=over 4 7668651Skris 7768651Skris=item E<gt>0 7868651Skris 7968651SkrisThe write operation was successful, the return value is the number of 8068651Skrisbytes actually written to the TLS/SSL connection. 8168651Skris 8268651Skris=item 0 8368651Skris 8489837SkrisThe write operation was not successful. Probably the underlying connection 8589837Skriswas closed. Call SSL_get_error() with the return value B<ret> to find out, 8689837Skriswhether an error occurred or the connection was shut down cleanly 8789837Skris(SSL_ERROR_ZERO_RETURN). 8868651Skris 8989837SkrisSSLv2 (deprecated) does not support a shutdown alert protocol, so it can 9089837Skrisonly be detected, whether the underlying connection was closed. It cannot 9189837Skrisbe checked, why the closure happened. 9289837Skris 9372613Skris=item E<lt>0 9468651Skris 9572613SkrisThe write operation was not successful, because either an error occurred 9668651Skrisor action must be taken by the calling process. Call SSL_get_error() with the 9768651Skrisreturn value B<ret> to find out the reason. 9868651Skris 9968651Skris=back 10068651Skris 10168651Skris=head1 SEE ALSO 10268651Skris 10368651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, 10476866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 10576866SkrisL<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 10676866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 10768651SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 10868651Skris 10968651Skris=cut 110