1: =pod
    2: 
    3: =head1 NAME
    4: 
    5: SSL_SESSION_free - free an allocated SSL_SESSION structure
    6: 
    7: =head1 SYNOPSIS
    8: 
    9:  #include <openssl/ssl.h>
   10: 
   11:  void SSL_SESSION_free(SSL_SESSION *session);
   12: 
   13: =head1 DESCRIPTION
   14: 
   15: SSL_SESSION_free() decrements the reference count of B<session> and removes
   16: the B<SSL_SESSION> structure pointed to by B<session> and frees up the allocated
   17: memory, if the the reference count has reached 0.
   18: 
   19: =head1 NOTES
   20: 
   21: SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
   22: is successfully completed. Depending on the settings, see
   23: L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
   24: the SSL_SESSION objects are internally referenced by the SSL_CTX and
   25: linked into its session cache. SSL objects may be using the SSL_SESSION object;
   26: as a session may be reused, several SSL objects may be using one SSL_SESSION
   27: object at the same time. It is therefore crucial to keep the reference
   28: count (usage information) correct and not delete a SSL_SESSION object
   29: that is still used, as this may lead to program failures due to
   30: dangling pointers. These failures may also appear delayed, e.g.
   31: when an SSL_SESSION object was completely freed as the reference count
   32: incorrectly became 0, but it is still referenced in the internal
   33: session cache and the cache list is processed during a
   34: L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)> operation.
   35: 
   36: SSL_SESSION_free() must only be called for SSL_SESSION objects, for
   37: which the reference count was explicitly incremented (e.g.
   38: by calling SSL_get1_session(), see L<SSL_get_session(3)|SSL_get_session(3)>)
   39: or when the SSL_SESSION object was generated outside a TLS handshake
   40: operation, e.g. by using L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>.
   41: It must not be called on other SSL_SESSION objects, as this would cause
   42: incorrect reference counts and therefore program failures.
   43: 
   44: =head1 RETURN VALUES
   45: 
   46: SSL_SESSION_free() does not provide diagnostic information.
   47: 
   48: =head1 SEE ALSO
   49: 
   50: L<ssl(3)|ssl(3)>, L<SSL_get_session(3)|SSL_get_session(3)>,
   51: L<SSL_CTX_set_session_cache_mode(3)|SSL_CTX_set_session_cache_mode(3)>,
   52: L<SSL_CTX_flush_sessions(3)|SSL_CTX_flush_sessions(3)>,
   53:  L<d2i_SSL_SESSION(3)|d2i_SSL_SESSION(3)>
   54: 
   55: =cut