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