secure/lib/libcrypto/man/SSL_SESSION_free.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "SSL_SESSION_FREE 3"
 132 .TH SSL_SESSION_FREE 3 "2018-09-11" "1.1.1" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 SSL_SESSION_new, SSL_SESSION_dup, SSL_SESSION_up_ref, SSL_SESSION_free \- create, free and manage SSL_SESSION structures
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/ssl.h>
 143 \&
 144 \& SSL_SESSION *SSL_SESSION_new(void);
 145 \& SSL_SESSION *SSL_SESSION_dup(SSL_SESSION *src);
 146 \& int SSL_SESSION_up_ref(SSL_SESSION *ses);
 147 \& void SSL_SESSION_free(SSL_SESSION *session);
 148 .Ve
 149 .SH "DESCRIPTION"
 150 .IX Header "DESCRIPTION"
 151 \&\fISSL_SESSION_new()\fR creates a new \s-1SSL_SESSION\s0 structure and returns a pointer to
 152 it.
 153 .PP
 154 \&\fISSL_SESSION_dup()\fR copies the contents of the \s-1SSL_SESSION\s0 structure in \fBsrc\fR
 155 and returns a pointer to it.
 156 .PP
 157 \&\fISSL_SESSION_up_ref()\fR increments the reference count on the given \s-1SSL_SESSION\s0
 158 structure.
 159 .PP
 160 \&\fISSL_SESSION_free()\fR decrements the reference count of \fBsession\fR and removes
 161 the \fB\s-1SSL_SESSION\s0\fR structure pointed to by \fBsession\fR and frees up the allocated
 162 memory, if the reference count has reached 0.
 163 If \fBsession\fR is \s-1NULL\s0 nothing is done.
 164 .SH "NOTES"
 165 .IX Header "NOTES"
 166 \&\s-1SSL_SESSION\s0 objects are allocated, when a \s-1TLS/SSL\s0 handshake operation
 167 is successfully completed. Depending on the settings, see
 168 \&\fISSL_CTX_set_session_cache_mode\fR\|(3),
 169 the \s-1SSL_SESSION\s0 objects are internally referenced by the \s-1SSL_CTX\s0 and
 170 linked into its session cache. \s-1SSL\s0 objects may be using the \s-1SSL_SESSION\s0 object;
 171 as a session may be reused, several \s-1SSL\s0 objects may be using one \s-1SSL_SESSION\s0
 172 object at the same time. It is therefore crucial to keep the reference
 173 count (usage information) correct and not delete a \s-1SSL_SESSION\s0 object
 174 that is still used, as this may lead to program failures due to
 175 dangling pointers. These failures may also appear delayed, e.g.
 176 when an \s-1SSL_SESSION\s0 object was completely freed as the reference count
 177 incorrectly became 0, but it is still referenced in the internal
 178 session cache and the cache list is processed during a
 179 \&\fISSL_CTX_flush_sessions\fR\|(3) operation.
 180 .PP
 181 \&\fISSL_SESSION_free()\fR must only be called for \s-1SSL_SESSION\s0 objects, for
 182 which the reference count was explicitly incremented (e.g.
 183 by calling \fISSL_get1_session()\fR, see \fISSL_get_session\fR\|(3))
 184 or when the \s-1SSL_SESSION\s0 object was generated outside a \s-1TLS\s0 handshake
 185 operation, e.g. by using \fId2i_SSL_SESSION\fR\|(3).
 186 It must not be called on other \s-1SSL_SESSION\s0 objects, as this would cause
 187 incorrect reference counts and therefore program failures.
 188 .SH "RETURN VALUES"
 189 .IX Header "RETURN VALUES"
 190 SSL_SESSION_new returns a pointer to the newly allocated \s-1SSL_SESSION\s0 structure
 191 or \s-1NULL\s0 on error.
 192 .PP
 193 SSL_SESSION_up_ref returns 1 on success or 0 on error.
 194 .SH "SEE ALSO"
 195 .IX Header "SEE ALSO"
 196 \&\fIssl\fR\|(7), \fISSL_get_session\fR\|(3),
 197 \&\fISSL_CTX_set_session_cache_mode\fR\|(3),
 198 \&\fISSL_CTX_flush_sessions\fR\|(3),
 199 \&\fId2i_SSL_SESSION\fR\|(3)
 200 .SH "HISTORY"
 201 .IX Header "HISTORY"
 202 \&\fISSL_SESSION_dup()\fR was added in OpenSSL 1.1.1.
 203 .SH "COPYRIGHT"
 204 .IX Header "COPYRIGHT"
 205 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 206 .PP
 207 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 208 this file except in compliance with the License.  You can obtain a copy
 209 in the file \s-1LICENSE\s0 in the source distribution or at
 210 <https://www.openssl.org/source/license.html>.