SSL_write.pod revision 72613
1249259Sdim=pod 2249259Sdim 3249259Sdim=head1 NAME 4249259Sdim 5249259SdimSSL_write - write bytes to a TLS/SSL connection. 6249259Sdim 7249259Sdim=head1 SYNOPSIS 8249259Sdim 9249259Sdim #include <openssl/ssl.h> 10249259Sdim 11249259Sdim int SSL_write(SSL *ssl, char *buf, int num); 12249259Sdim 13249259Sdim=head1 DESCRIPTION 14249259Sdim 15249259SdimSSL_write() writes B<num> bytes from the buffer B<buf> into the specified 16249259SdimB<ssl> connection. 17249259Sdim 18249259Sdim=head1 NOTES 19249259Sdim 20249259SdimIf necessary, SSL_write() will negotiate a TLS/SSL session, if 21249259Sdimnot already explicitly performed by SSL_connect() or SSL_accept(). If the 22249259Sdimpeer requests a re-negotiation, it will be performed transparently during 23249259Sdimthe SSL_write() operation. The behaviour of SSL_write() depends on the 24249259Sdimunderlying BIO. 25249259Sdim 26249259SdimIf the underlying BIO is B<blocking>, SSL_write() will only return, once the 27249259Sdimwrite operation has been finished or an error occurred. 28249259Sdim 29249259SdimIf the underlying BIO is B<non-blocking>, SSL_write() will also return, 30249259Sdimwhen the underlying BIO could not satisfy the needs of SSL_write() 31249259Sdimto continue the operation. In this case a call to SSL_get_error() with the 32249259Sdimreturn value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or 33249259SdimB<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 34249259Sdimcall to SSL_write() can also cause read operations! The calling process 35249259Sdimthen must repeat the call after taking appropriate action to satisfy the 36249259Sdimneeds of SSL_write(). The action depends on the underlying BIO. When using a 37249259Sdimnon-blocking socket, nothing is to be done, but select() can be used to check 38249259Sdimfor the required condition. When using a buffering BIO, like a BIO pair, data 39249259Sdimmust be written into or retrieved out of the BIO before being able to continue. 40249259Sdim 41249259Sdim=head1 WARNING 42249259Sdim 43249259SdimWhen an SSL_write() operation has to be repeated because of 44249259SdimB<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 45249259Sdimwith the same arguments. 46249259Sdim 47249259Sdim=head1 RETURN VALUES 48249259Sdim 49249259SdimThe following return values can occur: 50249259Sdim 51249259Sdim=over 4 52249259Sdim 53249259Sdim=item E<gt>0 54249259Sdim 55249259SdimThe write operation was successful, the return value is the number of 56249259Sdimbytes actually written to the TLS/SSL connection. 57249259Sdim 58249259Sdim=item 0 59249259Sdim 60249259SdimThe write operation was not successful. Call SSL_get_error() with the return 61249259Sdimvalue B<ret> to find out, whether an error occurred. 62249259Sdim 63249259Sdim=item E<lt>0 64249259Sdim 65249259SdimThe write operation was not successful, because either an error occurred 66249259Sdimor action must be taken by the calling process. Call SSL_get_error() with the 67249259Sdimreturn value B<ret> to find out the reason. 68249259Sdim 69249259Sdim=back 70249259Sdim 71249259Sdim=head1 SEE ALSO 72249259Sdim 73249259SdimL<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>, 74249259SdimL<ssl(3)|ssl(3)>, L<bio(3)|bio(3)> 75249259Sdim 76249259Sdim=cut 77249259Sdim