More manual pages. Constify.

diff --git a/doc/ssl/SSL_rstate_string.pod b/doc/ssl/SSL_rstate_string.pod
new file mode 100644 (file)
index 0000000..bdb8a1f
--- /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 (file)
index 0000000..39ca5f2
--- /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 816f1f6f874d1af8e77e0405e76c49864e2162a7..5cee288442e276cda8621e3620ca0323b5888502 100644 (file)
--- 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 8f5d0a4d4754c8d00146490613d9ef4888e75402..c5f24eb51c38f28f2d69fabe72b0e4f2bf60af17 100644 (file)
--- 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 8e2b874f61b113b2f6aab94ab484c93d7e5dfc64..963a50267830103400bc93c489a3f21293467b30 100644 (file)
--- 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)
                {