Merge branch 'topic/doc-ssl-sync-close'

* topic/doc-ssl-sync-close:
  Document OpenSSL::SSL::SSLSocket#sync_close

2 files changed, 10 insertions, 0 deletions

diff --git a/ext/openssl/ossl.c b/ext/openssl/ossl.c
index 83baa7b6..1af9b247 100644
--- a/ext/openssl/ossl.c
+++ b/ext/openssl/ossl.c
@@ -1063,15 +1063,21 @@ static void Init_ossl_locks(void)
  * SSLSocket#connect must be called to initiate the SSL handshake and start
  * encryption.  A key and certificate are not required for the client socket.
  *
+ * Note that SSLSocket#close doesn't close the underlying socket by default. Set
+ * SSLSocket#sync_close to true if you want.
+ *
  *   require 'socket'
  *
  *   tcp_socket = TCPSocket.new 'localhost', 5000
  *   ssl_client = OpenSSL::SSL::SSLSocket.new tcp_socket, context
+ *   ssl_client.sync_close = true
  *   ssl_client.connect
  *
  *   ssl_client.puts "hello server!"
  *   puts ssl_client.gets
  *
+ *   ssl_client.close # shutdown the TLS connection and close tcp_socket
+ *
  * === Peer Verification
  *
  * An unverified SSL connection does not provide much security.  For enhanced
diff --git a/lib/openssl/ssl.rb b/lib/openssl/ssl.rb
index 1c0ca94d..9cac6925 100644
--- a/lib/openssl/ssl.rb
+++ b/lib/openssl/ssl.rb
@@ -249,7 +249,11 @@ module OpenSSL
       end
 
       attr_reader :io, :context
+
+      # Whether to close the underlying socket as well, when the SSL/TLS
+      # connection is shut down. This defaults to +false+.
       attr_accessor :sync_close
+
       alias :to_io :io
 
       # call-seq: