secure/lib/libcrypto/man/SSL_SESSION_free.3

   1 .\" Automatically generated by Pod::Man 4.11 (Pod::Simple 3.39)
   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 .nr rF 0
  58 .if \n(.g .if rF .nr rF 1
  59 .if (\n(rF:(\n(.g==0)) \{\
  60 .    if \nF \{\
  61 .        de IX
  62 .        tm Index:\\$1\t\\n%\t"\\$2"
  63 ..
  64 .        if !\nF==2 \{\
  65 .            nr % 0
  66 .            nr F 2
  67 .        \}
  68 .    \}
  69 .\}
  70 .rr rF
  71 .\"
  72 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  73 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  74 .    \" fudge factors for nroff and troff
  75 .if n \{\
  76 .    ds #H 0
  77 .    ds #V .8m
  78 .    ds #F .3m
  79 .    ds #[ \f1
  80 .    ds #] \fP
  81 .\}
  82 .if t \{\
  83 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  84 .    ds #V .6m
  85 .    ds #F 0
  86 .    ds #[ \&
  87 .    ds #] \&
  88 .\}
  89 .    \" simple accents for nroff and troff
  90 .if n \{\
  91 .    ds ' \&
  92 .    ds ` \&
  93 .    ds ^ \&
  94 .    ds , \&
  95 .    ds ~ ~
  96 .    ds /
  97 .\}
  98 .if t \{\
  99 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 100 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 101 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 102 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 103 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 104 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 105 .\}
 106 .    \" troff and (daisy-wheel) nroff accents
 107 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 108 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 109 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 110 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 111 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 112 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 113 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 114 .ds ae a\h'-(\w'a'u*4/10)'e
 115 .ds Ae A\h'-(\w'A'u*4/10)'E
 116 .    \" corrections for vroff
 117 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 118 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 119 .    \" for low resolution devices (crt and lpr)
 120 .if \n(.H>23 .if \n(.V>19 \
 121 \{\
 122 .    ds : e
 123 .    ds 8 ss
 124 .    ds o a
 125 .    ds d- d\h'-1'\(ga
 126 .    ds D- D\h'-1'\(hy
 127 .    ds th \o'bp'
 128 .    ds Th \o'LP'
 129 .    ds ae ae
 130 .    ds Ae AE
 131 .\}
 132 .rm #[ #] #H #V #F C
 133 .\" ========================================================================
 134 .\"
 135 .IX Title "SSL_SESSION_FREE 3"
 136 .TH SSL_SESSION_FREE 3 "2019-09-10" "1.1.1d" "OpenSSL"
 137 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 138 .\" way too many mistakes in technical documents.
 139 .if n .ad l
 140 .nh
 141 .SH "NAME"
 142 SSL_SESSION_new, SSL_SESSION_dup, SSL_SESSION_up_ref, SSL_SESSION_free \- create, free and manage SSL_SESSION structures
 143 .SH "SYNOPSIS"
 144 .IX Header "SYNOPSIS"
 145 .Vb 1
 146 \& #include <openssl/ssl.h>
 147 \&
 148 \& SSL_SESSION *SSL_SESSION_new(void);
 149 \& SSL_SESSION *SSL_SESSION_dup(SSL_SESSION *src);
 150 \& int SSL_SESSION_up_ref(SSL_SESSION *ses);
 151 \& void SSL_SESSION_free(SSL_SESSION *session);
 152 .Ve
 153 .SH "DESCRIPTION"
 154 .IX Header "DESCRIPTION"
 155 \&\fBSSL_SESSION_new()\fR creates a new \s-1SSL_SESSION\s0 structure and returns a pointer to
 156 it.
 157 .PP
 158 \&\fBSSL_SESSION_dup()\fR copies the contents of the \s-1SSL_SESSION\s0 structure in \fBsrc\fR
 159 and returns a pointer to it.
 160 .PP
 161 \&\fBSSL_SESSION_up_ref()\fR increments the reference count on the given \s-1SSL_SESSION\s0
 162 structure.
 163 .PP
 164 \&\fBSSL_SESSION_free()\fR decrements the reference count of \fBsession\fR and removes
 165 the \fB\s-1SSL_SESSION\s0\fR structure pointed to by \fBsession\fR and frees up the allocated
 166 memory, if the reference count has reached 0.
 167 If \fBsession\fR is \s-1NULL\s0 nothing is done.
 168 .SH "NOTES"
 169 .IX Header "NOTES"
 170 \&\s-1SSL_SESSION\s0 objects are allocated, when a \s-1TLS/SSL\s0 handshake operation
 171 is successfully completed. Depending on the settings, see
 172 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
 173 the \s-1SSL_SESSION\s0 objects are internally referenced by the \s-1SSL_CTX\s0 and
 174 linked into its session cache. \s-1SSL\s0 objects may be using the \s-1SSL_SESSION\s0 object;
 175 as a session may be reused, several \s-1SSL\s0 objects may be using one \s-1SSL_SESSION\s0
 176 object at the same time. It is therefore crucial to keep the reference
 177 count (usage information) correct and not delete a \s-1SSL_SESSION\s0 object
 178 that is still used, as this may lead to program failures due to
 179 dangling pointers. These failures may also appear delayed, e.g.
 180 when an \s-1SSL_SESSION\s0 object was completely freed as the reference count
 181 incorrectly became 0, but it is still referenced in the internal
 182 session cache and the cache list is processed during a
 183 \&\fBSSL_CTX_flush_sessions\fR\|(3) operation.
 184 .PP
 185 \&\fBSSL_SESSION_free()\fR must only be called for \s-1SSL_SESSION\s0 objects, for
 186 which the reference count was explicitly incremented (e.g.
 187 by calling \fBSSL_get1_session()\fR, see \fBSSL_get_session\fR\|(3))
 188 or when the \s-1SSL_SESSION\s0 object was generated outside a \s-1TLS\s0 handshake
 189 operation, e.g. by using \fBd2i_SSL_SESSION\fR\|(3).
 190 It must not be called on other \s-1SSL_SESSION\s0 objects, as this would cause
 191 incorrect reference counts and therefore program failures.
 192 .SH "RETURN VALUES"
 193 .IX Header "RETURN VALUES"
 194 SSL_SESSION_new returns a pointer to the newly allocated \s-1SSL_SESSION\s0 structure
 195 or \s-1NULL\s0 on error.
 196 .PP
 197 SSL_SESSION_up_ref returns 1 on success or 0 on error.
 198 .SH "SEE ALSO"
 199 .IX Header "SEE ALSO"
 200 \&\fBssl\fR\|(7), \fBSSL_get_session\fR\|(3),
 201 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
 202 \&\fBSSL_CTX_flush_sessions\fR\|(3),
 203 \&\fBd2i_SSL_SESSION\fR\|(3)
 204 .SH "HISTORY"
 205 .IX Header "HISTORY"
 206 The \fBSSL_SESSION_dup()\fR function was added in OpenSSL 1.1.1.
 207 .SH "COPYRIGHT"
 208 .IX Header "COPYRIGHT"
 209 Copyright 2000\-2016 The OpenSSL Project Authors. All Rights Reserved.
 210 .PP
 211 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 212 this file except in compliance with the License.  You can obtain a copy
 213 in the file \s-1LICENSE\s0 in the source distribution or at
 214 <https://www.openssl.org/source/license.html>.