1=pod 2 3=head1 NAME 4 5SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection 6 7=head1 SYNOPSIS 8 9 #include <openssl/ssl.h> 10 11 int SSL_write_ex(SSL *s, const void *buf, size_t num, size_t *written); 12 int SSL_write(SSL *ssl, const void *buf, int num); 13 14=head1 DESCRIPTION 15 16SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into 17the specified B<ssl> connection. On success SSL_write_ex() will store the number 18of bytes written in B<*written>. 19 20=head1 NOTES 21 22In the paragraphs below a "write function" is defined as one of either 23SSL_write_ex(), or SSL_write(). 24 25If necessary, a write function will negotiate a TLS/SSL session, if not already 26explicitly performed by L<SSL_connect(3)> or L<SSL_accept(3)>. If the peer 27requests a re-negotiation, it will be performed transparently during 28the write function operation. The behaviour of the write functions depends on the 29underlying BIO. 30 31For the transparent negotiation to succeed, the B<ssl> must have been 32initialized to client or server mode. This is being done by calling 33L<SSL_set_connect_state(3)> or SSL_set_accept_state() 34before the first call to a write function. 35 36If the underlying BIO is B<blocking>, the write functions will only return, once 37the write operation has been finished or an error occurred. 38 39If the underlying BIO is B<nonblocking> the write functions will also return 40when the underlying BIO could not satisfy the needs of the function to continue 41the operation. In this case a call to L<SSL_get_error(3)> with the 42return value of the write function will yield B<SSL_ERROR_WANT_READ> 43or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a 44call to a write function can also cause read operations! The calling process 45then must repeat the call after taking appropriate action to satisfy the needs 46of the write function. The action depends on the underlying BIO. When using a 47nonblocking socket, nothing is to be done, but select() can be used to check 48for the required condition. When using a buffering BIO, like a BIO pair, data 49must be written into or retrieved out of the BIO before being able to continue. 50 51The write functions will only return with success when the complete contents of 52B<buf> of length B<num> has been written. This default behaviour can be changed 53with the SSL_MODE_ENABLE_PARTIAL_WRITE option of L<SSL_CTX_set_mode(3)>. When 54this flag is set the write functions will also return with success when a 55partial write has been successfully completed. In this case the write function 56operation is considered completed. The bytes are sent and a new write call with 57a new buffer (with the already sent bytes removed) must be started. A partial 58write is performed with the size of a message block, which is 16kB. 59 60=head1 WARNINGS 61 62When a write function call has to be repeated because L<SSL_get_error(3)> 63returned B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated 64with the same arguments. 65The data that was passed might have been partially processed. 66When B<SSL_MODE_ACCEPT_MOVING_WRITE_BUFFER> was set using L<SSL_CTX_set_mode(3)> 67the pointer can be different, but the data and length should still be the same. 68 69You should not call SSL_write() with num=0, it will return an error. 70SSL_write_ex() can be called with num=0, but will not send application data to 71the peer. 72 73=head1 RETURN VALUES 74 75SSL_write_ex() will return 1 for success or 0 for failure. Success means that 76all requested application data bytes have been written to the SSL connection or, 77if SSL_MODE_ENABLE_PARTIAL_WRITE is in use, at least 1 application data byte has 78been written to the SSL connection. Failure means that not all the requested 79bytes have been written yet (if SSL_MODE_ENABLE_PARTIAL_WRITE is not in use) or 80no bytes could be written to the SSL connection (if 81SSL_MODE_ENABLE_PARTIAL_WRITE is in use). Failures can be retryable (e.g. the 82network write buffer has temporarily filled up) or non-retryable (e.g. a fatal 83network error). In the event of a failure call L<SSL_get_error(3)> to find out 84the reason which indicates whether the call is retryable or not. 85 86For SSL_write() the following return values can occur: 87 88=over 4 89 90=item E<gt> 0 91 92The write operation was successful, the return value is the number of 93bytes actually written to the TLS/SSL connection. 94 95=item Z<><= 0 96 97The write operation was not successful, because either the connection was 98closed, an error occurred or action must be taken by the calling process. 99Call SSL_get_error() with the return value B<ret> to find out the reason. 100 101Old documentation indicated a difference between 0 and -1, and that -1 was 102retryable. 103You should instead call SSL_get_error() to find out if it's retryable. 104 105=back 106 107=head1 SEE ALSO 108 109L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)> 110L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>, 111L<SSL_connect(3)>, L<SSL_accept(3)> 112L<SSL_set_connect_state(3)>, 113L<ssl(7)>, L<bio(7)> 114 115=head1 HISTORY 116 117The SSL_write_ex() function was added in OpenSSL 1.1.1. 118 119=head1 COPYRIGHT 120 121Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved. 122 123Licensed under the OpenSSL license (the "License"). You may not use 124this file except in compliance with the License. You can obtain a copy 125in the file LICENSE in the source distribution or at 126L<https://www.openssl.org/source/license.html>. 127 128=cut 129