A comment.

ssl/ssl_lib.c

@@ -657,6 +657,12 @@ int SSL_write(SSL *s,const char *buf,int num)
 
 int SSL_shutdown(SSL *s)
 	{
+	/* Note that this function behaves different from what one might
+	 * expect.  Return values are 0 for no success (yet),
+	 * 1 for success; but calling it once is usually not enough,
+	 * even if blocking I/O is used (see ssl3_shutdown).
+	 */
+
 	if (s->handshake_func == 0)
 		{
 		SSLerr(SSL_F_SSL_SHUTDOWN, SSL_R_UNINITIALIZED);