SSL_write.pod revision 79998
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 2876866Skrisinitialized to client or server mode. This is not the case if a generic 2976866Skrismethod is being used (see L<SSL_CTX_new(3)|SSL_CTX_new(3)>, so that 3076866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state() 3176866Skrismust be used before the first call to an L<SSL_read(3)|SSL_read(3)> 3276866Skrisor SSL_write() function. 3376866Skris 3468651SkrisIf the underlying BIO is B<blocking>, SSL_write() will only return, once the 3576866Skriswrite operation has been finished or an error occurred, except when a 3676866Skrisrenegotiation take place, in which case a SSL_ERROR_WANT_READ may occur. 3776866SkrisThis behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the 3876866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call. 3968651Skris 4068651SkrisIf the underlying BIO is B<non-blocking>, SSL_write() will also return, 4168651Skriswhen the underlying BIO could not satisfy the needs of SSL_write() 4276866Skristo continue the operation. In this case a call to 4376866SkrisL<SSL_get_error(3)|SSL_get_error(3)> with the 4468651Skrisreturn value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or 4568651SkrisB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 4672613Skriscall to SSL_write() can also cause read operations! The calling process 4768651Skristhen must repeat the call after taking appropriate action to satisfy the 4868651Skrisneeds of SSL_write(). The action depends on the underlying BIO. When using a 4968651Skrisnon-blocking socket, nothing is to be done, but select() can be used to check 5068651Skrisfor the required condition. When using a buffering BIO, like a BIO pair, data 5168651Skrismust be written into or retrieved out of the BIO before being able to continue. 5268651Skris 5379998SkrisSSL_write() will only return with success, when the complete contents 5479998Skrisof B<buf> of length B<num> has been written. This default behaviour 5579998Skriscan be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of 5679998SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set, 5779998SkrisSSL_write() will also return with success, when a partial write has been 5879998Skrissuccessfully completed. In this case the SSL_write() operation is considered 5979998Skriscompleted. The bytes are sent and a new SSL_write() operation with a new 6079998Skrisbuffer (with the already sent bytes removed) must be started. 6179998SkrisA partial write is performed with the size of a message block, which is 6279998Skris16kB for SSLv3/TLSv1. 6379998Skris 6468651Skris=head1 WARNING 6568651Skris 6668651SkrisWhen an SSL_write() operation has to be repeated because of 6768651SkrisB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 6868651Skriswith the same arguments. 6968651Skris 7068651Skris=head1 RETURN VALUES 7168651Skris 7268651SkrisThe following return values can occur: 7368651Skris 7468651Skris=over 4 7568651Skris 7668651Skris=item E<gt>0 7768651Skris 7868651SkrisThe write operation was successful, the return value is the number of 7968651Skrisbytes actually written to the TLS/SSL connection. 8068651Skris 8168651Skris=item 0 8268651Skris 8368651SkrisThe write operation was not successful. Call SSL_get_error() with the return 8468651Skrisvalue B<ret> to find out, whether an error occurred. 8568651Skris 8672613Skris=item E<lt>0 8768651Skris 8872613SkrisThe write operation was not successful, because either an error occurred 8968651Skrisor action must be taken by the calling process. Call SSL_get_error() with the 9068651Skrisreturn value B<ret> to find out the reason. 9168651Skris 9268651Skris=back 9368651Skris 9468651Skris=head1 SEE ALSO 9568651Skris 9668651SkrisL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, 9776866SkrisL<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>, 9876866SkrisL<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)> 9976866SkrisL<SSL_set_connect_state(3)|SSL_set_connect_state(3)>, 10068651SkrisL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 10168651Skris 10268651Skris=cut 103