More manual pages. Constify.

5 files changed, 128 insertions, 22 deletions

diff --git a/doc/ssl/SSL_rstate_string.pod b/doc/ssl/SSL_rstate_string.pod
new file mode 100644
index 0000000000..bdb8a1fcd5
--- /dev/null
+++ b/doc/ssl/SSL_rstate_string.pod
@@ -0,0 +1,59 @@
+=pod
+
+=head1 NAME
+
+SSL_rstate_string, SSL_rstate_string_long - get textual description of state of an SSL object during read operation
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_rstate_string(SSL *ssl);
+ const char *SSL_rstate_string_long(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_rstate_string() returns a 2 letter string indicating the current read state
+of the SSL object B<ssl>.
+
+SSL_rstate_string_long() returns a string indicating the current read state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+When performing a read operation, the SSL/TLS engine must parse the record,
+consisting of header and body. When working in a blocking environment,
+SSL_rstate_string[_long]() should always return "RD"/"read done".
+
+This function should only seldom be needed in applications.
+
+=head1 RETURN VALUES
+
+SSL_rstate_string() and SSL_rstate_string_long() can return the following
+values:
+
+=over 4
+
+=item "RH"/"read header"
+
+The header of the record is being evaluated.
+
+=item "RB"/"read body"
+
+The body of the record is being evaluated.
+
+=item "RD"/"read done"
+
+The record has been completely processed.
+
+=item "unknown"/"unknown"
+
+The read state is unknown. This should never happen.
+
+=back
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/doc/ssl/SSL_state_string.pod b/doc/ssl/SSL_state_string.pod
new file mode 100644
index 0000000000..39ca5f29fa
--- /dev/null
+++ b/doc/ssl/SSL_state_string.pod
@@ -0,0 +1,45 @@
+=pod
+
+=head1 NAME
+
+SSL_state_string, SSL_state_string_long - get textual description of state of an SSL object
+
+=head1 SYNOPSIS
+
+ #include <openssl/ssl.h>
+
+ const char *SSL_state_string(SSL *ssl);
+ const char *SSL_state_string_long(SSL *ssl);
+
+=head1 DESCRIPTION
+
+SSL_state_string() returns a 6 letter string indicating the current state
+of the SSL object B<ssl>.
+
+SSL_state_string_long() returns a string indicating the current state of
+the SSL object B<ssl>.
+
+=head1 NOTES
+
+During its use, an SSL objects passes several states. The state is internally
+maintained. Querying the state information is not very informative before
+or when a connection has been established. It however can be of significant
+interest during the handshake.
+
+When using non-blocking sockets, the function call performing the handshake
+may return with SSL_ERROR_WANT_READ or SSL_ERROR_WANT_WRITE condition,
+so that SSL_state_string[_long]() may be called.
+
+For both blocking or non-blocking sockets, the details state information
+can be used within the info_callback function set with the
+SSL_set_info_callback() call.
+
+=head1 RETURN VALUES
+
+Detailed description of possible states to be included later.
+
+=head1 SEE ALSO
+
+L<ssl(3)|ssl(3)>
+
+=cut
diff --git a/doc/ssl/ssl.pod b/doc/ssl/ssl.pod
index 816f1f6f87..5cee288442 100644
--- a/doc/ssl/ssl.pod
+++ b/doc/ssl/ssl.pod
@@ -698,6 +698,7 @@ L<SSL_load_client_CA_file(3)|SSL_load_client_CA_file(3)>,
 L<SSL_new(3)|SSL_new(3)>,
 L<SSL_pending(3)|SSL_pending(3)>,
 L<SSL_read(3)|SSL_read(3)>,
+L<SSL_rstate_string(3)|SSL_rstate_string(3)>,
 L<SSL_session_reused(3)|SSL_session_reused(3)>,
 L<SSL_set_bio(3)|SSL_set_bio(3)>,
 L<SSL_set_connect_state(3)|SSL_set_connect_state(3)>,
@@ -705,6 +706,7 @@ L<SSL_set_fd(3)|SSL_set_fd(3)>,
 L<SSL_set_session(3)|SSL_set_session(3)>,
 L<SSL_set_shutdown(3)|SSL_set_shutdown(3)>,
 L<SSL_shutdown(3)|SSL_shutdown(3)>,
+L<SSL_state_string(3)|SSL_state_string(3)>,
 L<SSL_want(3)|SSL_want(3)>,
 L<SSL_write(3)|SSL_write(3)>,
 L<SSL_SESSION_free(3)|SSL_SESSION_free(3)>,
diff --git a/ssl/ssl.h b/ssl/ssl.h
index 8f5d0a4d47..c5f24eb51c 100644
--- a/ssl/ssl.h
+++ b/ssl/ssl.h
@@ -1038,10 +1038,10 @@ int	SSL_add_dir_cert_subjects_to_stack(STACK_OF(X509_NAME) *stackCAs,
 
 void	ERR_load_SSL_strings(void );
 void	SSL_load_error_strings(void );
-char * 	SSL_state_string(SSL *s);
-char * 	SSL_rstate_string(SSL *s);
-char * 	SSL_state_string_long(SSL *s);
-char * 	SSL_rstate_string_long(SSL *s);
+const char *SSL_state_string(SSL *s);
+const char *SSL_rstate_string(SSL *s);
+const char *SSL_state_string_long(SSL *s);
+const char *SSL_rstate_string_long(SSL *s);
 long	SSL_SESSION_get_time(SSL_SESSION *s);
 long	SSL_SESSION_set_time(SSL_SESSION *s, long t);
 long	SSL_SESSION_get_timeout(SSL_SESSION *s);
@@ -1150,10 +1150,10 @@ int SSL_shutdown(SSL *s);
 
 SSL_METHOD *SSL_get_ssl_method(SSL *s);
 int SSL_set_ssl_method(SSL *s,SSL_METHOD *method);
-char *SSL_alert_type_string_long(int value);
-char *SSL_alert_type_string(int value);
-char *SSL_alert_desc_string_long(int value);
-char *SSL_alert_desc_string(int value);
+const char *SSL_alert_type_string_long(int value);
+const char *SSL_alert_type_string(int value);
+const char *SSL_alert_desc_string_long(int value);
+const char *SSL_alert_desc_string(int value);
 
 void SSL_set_client_CA_list(SSL *s, STACK_OF(X509_NAME) *list);
 void SSL_CTX_set_client_CA_list(SSL_CTX *ctx, STACK_OF(X509_NAME) *list);
diff --git a/ssl/ssl_stat.c b/ssl/ssl_stat.c
index 8e2b874f61..963a502678 100644
--- a/ssl/ssl_stat.c
+++ b/ssl/ssl_stat.c
@@ -59,9 +59,9 @@
 #include <stdio.h>
 #include "ssl_locl.h"
 
-char *SSL_state_string_long(SSL *s)
+const char *SSL_state_string_long(SSL *s)
 	{
-	char *str;
+	const char *str;
 
 	switch (s->state)
 		{
@@ -199,9 +199,9 @@ default:	str="unknown state"; break;
 	return(str);
 	}
 
-char *SSL_rstate_string_long(SSL *s)
+const char *SSL_rstate_string_long(SSL *s)
 	{
-	char *str;
+	const char *str;
 
 	switch (s->rstate)
 		{
@@ -213,9 +213,9 @@ char *SSL_rstate_string_long(SSL *s)
 	return(str);
 	}
 
-char *SSL_state_string(SSL *s)
+const char *SSL_state_string(SSL *s)
 	{
-	char *str;
+	const char *str;
 
 	switch (s->state)
 		{
@@ -347,7 +347,7 @@ default:					str="UNKWN "; break;
 	return(str);
 	}
 
-char *SSL_alert_type_string_long(int value)
+const char *SSL_alert_type_string_long(int value)
 	{
 	value>>=8;
 	if (value == SSL3_AL_WARNING)
@@ -358,7 +358,7 @@ char *SSL_alert_type_string_long(int value)
 		return("unknown");
 	}
 
-char *SSL_alert_type_string(int value)
+const char *SSL_alert_type_string(int value)
 	{
 	value>>=8;
 	if (value == SSL3_AL_WARNING)
@@ -369,9 +369,9 @@ char *SSL_alert_type_string(int value)
 		return("U");
 	}
 
-char *SSL_alert_desc_string(int value)
+const char *SSL_alert_desc_string(int value)
 	{
-	char *str;
+	const char *str;
 
 	switch (value & 0xff)
 		{
@@ -404,9 +404,9 @@ char *SSL_alert_desc_string(int value)
 	return(str);
 	}
 
-char *SSL_alert_desc_string_long(int value)
+const char *SSL_alert_desc_string_long(int value)
 	{
-	char *str;
+	const char *str;
 
 	switch (value & 0xff)
 		{
@@ -487,9 +487,9 @@ char *SSL_alert_desc_string_long(int value)
 	return(str);
 	}
 
-char *SSL_rstate_string(SSL *s)
+const char *SSL_rstate_string(SSL *s)
 	{
-	char *str;
+	const char *str;
 
 	switch (s->rstate)
 		{