SSL_write.pod 4.1 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109
  1. =pod
  2. =head1 NAME
  3. SSL_write - write bytes to a TLS/SSL connection.
  4. =head1 SYNOPSIS
  5. #include <openssl/ssl.h>
  6. int SSL_write(SSL *ssl, const void *buf, int num);
  7. =head1 DESCRIPTION
  8. SSL_write() writes B<num> bytes from the buffer B<buf> into the specified
  9. B<ssl> connection.
  10. =head1 NOTES
  11. If necessary, SSL_write() will negotiate a TLS/SSL session, if
  12. not already explicitly performed by L<SSL_connect(3)|SSL_connect(3)> or
  13. L<SSL_accept(3)|SSL_accept(3)>. If the
  14. peer requests a re-negotiation, it will be performed transparently during
  15. the SSL_write() operation. The behaviour of SSL_write() depends on the
  16. underlying BIO.
  17. For the transparent negotiation to succeed, the B<ssl> must have been
  18. initialized to client or server mode. This is being done by calling
  19. L<SSL_set_connect_state(3)|SSL_set_connect_state(3)> or SSL_set_accept_state()
  20. before the first call to an L<SSL_read(3)|SSL_read(3)> or SSL_write() function.
  21. If the underlying BIO is B<blocking>, SSL_write() will only return, once the
  22. write operation has been finished or an error occurred, except when a
  23. renegotiation take place, in which case a SSL_ERROR_WANT_READ may occur.
  24. This behaviour can be controlled with the SSL_MODE_AUTO_RETRY flag of the
  25. L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)> call.
  26. If the underlying BIO is B<non-blocking>, SSL_write() will also return,
  27. when the underlying BIO could not satisfy the needs of SSL_write()
  28. to continue the operation. In this case a call to
  29. L<SSL_get_error(3)|SSL_get_error(3)> with the
  30. return value of SSL_write() will yield B<SSL_ERROR_WANT_READ> or
  31. B<SSL_ERROR_WANT_WRITE>. As at any time a re-negotiation is possible, a
  32. call to SSL_write() can also cause read operations! The calling process
  33. then must repeat the call after taking appropriate action to satisfy the
  34. needs of SSL_write(). The action depends on the underlying BIO. When using a
  35. non-blocking socket, nothing is to be done, but select() can be used to check
  36. for the required condition. When using a buffering BIO, like a BIO pair, data
  37. must be written into or retrieved out of the BIO before being able to continue.
  38. SSL_write() will only return with success, when the complete contents
  39. of B<buf> of length B<num> has been written. This default behaviour
  40. can be changed with the SSL_MODE_ENABLE_PARTIAL_WRITE option of
  41. L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>. When this flag is set,
  42. SSL_write() will also return with success, when a partial write has been
  43. successfully completed. In this case the SSL_write() operation is considered
  44. completed. The bytes are sent and a new SSL_write() operation with a new
  45. buffer (with the already sent bytes removed) must be started.
  46. A partial write is performed with the size of a message block, which is
  47. 16kB for SSLv3/TLSv1.
  48. =head1 WARNING
  49. When an SSL_write() operation has to be repeated because of
  50. B<SSL_ERROR_WANT_READ> or B<SSL_ERROR_WANT_WRITE>, it must be repeated
  51. with the same arguments.
  52. When calling SSL_write() with num=0 bytes to be sent the behaviour is
  53. undefined.
  54. =head1 RETURN VALUES
  55. The following return values can occur:
  56. =over 4
  57. =item E<gt>0
  58. The write operation was successful, the return value is the number of
  59. bytes actually written to the TLS/SSL connection.
  60. =item Z<>0
  61. The write operation was not successful. Probably the underlying connection
  62. was closed. Call SSL_get_error() with the return value B<ret> to find out,
  63. whether an error occurred or the connection was shut down cleanly
  64. (SSL_ERROR_ZERO_RETURN).
  65. SSLv2 (deprecated) does not support a shutdown alert protocol, so it can
  66. only be detected, whether the underlying connection was closed. It cannot
  67. be checked, why the closure happened.
  68. =item E<lt>0
  69. The write operation was not successful, because either an error occurred
  70. or action must be taken by the calling process. Call SSL_get_error() with the
  71. return value B<ret> to find out the reason.
  72. =back
  73. =head1 SEE ALSO
  74. L<SSL_get_error(3)|SSL_get_error(3)>, L<SSL_read(3)|SSL_read(3)>,
  75. L<SSL_CTX_set_mode(3)|SSL_CTX_set_mode(3)>, L<SSL_CTX_new(3)|SSL_CTX_new(3)>,
  76. L<SSL_connect(3)|SSL_connect(3)>, L<SSL_accept(3)|SSL_accept(3)>
  77. L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
  78. L<ssl(3)|ssl(3)>, L<bio(3)|bio(3)>
  79. =cut