5 SSL_write_ex, SSL_write - write bytes to a TLS/SSL connection
9 #include <openssl/ssl.h>
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);
16 SSL_write_ex() and SSL_write() write B<num> bytes from the buffer B<buf> into
17 the specified B<ssl> connection. On success SSL_write_ex() will store the number
18 of bytes written in B<*written>.
22 If necessary, SSL_write_ex() or SSL_write() will negotiate a TLS/SSL session, if
23 not already explicitly performed by L<SSL_connect(3)> or
24 L<SSL_accept(3)>. If the
25 peer requests a re-negotiation, it will be performed transparently during
26 the SSL_write_ex() or SSL_write() operation. The behaviour of SSL_write_ex() or
27 SSL_write() depends on the underlying BIO.
29 For the transparent negotiation to succeed, the B<ssl> must have been
30 initialized to client or server mode. This is being done by calling
31 L<SSL_set_connect_state(3)> or SSL_set_accept_state()
32 before the first call to an L<SSL_read_ex(3)>, L<SSL_read(3)>, SSL_write_ex() or
35 If the underlying BIO is B<blocking>, SSL_write_ex() and SSL_write() will only
36 return, once the write operation has been finished or an error occurred, except
37 when a renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
38 This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
39 L<SSL_CTX_set_mode(3)> call.
41 If the underlying BIO is B<non-blocking>, SSL_write_ex() or SSL_write() will
42 also return, when the underlying BIO could not satisfy the needs of
43 SSL_write_ex() or SSL_write() to continue the operation. In this case a call to
44 L<SSL_get_error(3)> with the
45 return value of SSL_write_ex() or SSL_write() will yield B<SSL_ERROR_WANT_READ>
46 or B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
47 call to SSL_write_ex() or SSL_write() can also cause read operations! The
48 calling process then must repeat the call after taking appropriate action to
49 satisfy the needs of SSL_write_ex() or SSL_write(). The action depends on the
50 underlying BIO. When using a non-blocking socket, nothing is to be done, but
51 select() can be used to check for the required condition. When using a buffering
52 BIO, like a BIO pair, data must be written into or retrieved out of the BIO
53 before being able to continue.
55 SSL_write_ex() or SSL_write() will only return with success, when the complete
56 contents of B<buf> of length B<num> has been written. This default behaviour
57 can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
58 L<SSL_CTX_set_mode(3)>. When this flag is set,
59 SSL_write_ex() or SSL_write() will also return with success, when a partial
60 write has been successfully completed. In this case the SSL_write_ex() or
61 SSL_write() operation is considered completed. The bytes are sent and a new
62 SSL_write_ex() or SSL_write() operation with a new
63 buffer (with the already sent bytes removed) must be started.
64 A partial write is performed with the size of a message block, which is
69 When an SSL_write_ex() or SSL_write() operation has to be repeated because of
70 B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
71 with the same arguments.
73 When calling SSL_write_ex() or SSL_write() with num=0 bytes to be sent the
74 behaviour is undefined.
78 SSL_write_ex() will return 1 for success or 0 for failure. In the event of a
79 failure call SSL_get_error() to find out the reason.
81 For SSL_write() the following return values can occur:
87 The write operation was successful, the return value is the number of
88 bytes actually written to the TLS/SSL connection.
92 The write operation was not successful. Probably the underlying connection
93 was closed. Call SSL_get_error() with the return value B<ret> to find out,
94 whether an error occurred or the connection was shut down cleanly
95 (SSL_ERROR_ZERO_RETURN).
99 The write operation was not successful, because either an error occurred
100 or action must be taken by the calling process. Call SSL_get_error() with the
101 return value B<ret> to find out the reason.
107 L<SSL_get_error(3)>, L<SSL_read_ex(3)>, L<SSL_read(3)>
108 L<SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)>,
109 L<SSL_connect(3)>, L<SSL_accept(3)>
110 L<SSL_set_connect_state(3)>,
115 Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
117 Licensed under the OpenSSL license (the "License"). You may not use
118 this file except in compliance with the License. You can obtain a copy
119 in the file LICENSE in the source distribution or at
120 L<https://www.openssl.org/source/license.html>.