Debian Codegraph @

upstream/debian-unstable/man3/SSL_SESSION_free.3ssl

raw
1 .\" -*- mode: troff; coding: utf-8 -*-
2 .\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45)
3 .\"
4 .\" Standard preamble:
5 .\" ========================================================================
6 .de Sp \" Vertical space (when we can't use .PP)
7 .if t .sp .5v
8 .if n .sp
9 ..
10 .de Vb \" Begin verbatim text
11 .ft CW
12 .nf
13 .ne \\$1
14 ..
15 .de Ve \" End verbatim text
16 .ft R
17 .fi
18 ..
19 .\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
20 .ie n \{\
21 . ds C` ""
22 . ds C' ""
23 'br\}
24 .el\{\
25 . ds C`
26 . ds C'
27 'br\}
28 .\"
29 .\" Escape single quotes in literal strings from groff's Unicode transform.
30 .ie \n(.g .ds Aq \(aq
31 .el .ds Aq '
32 .\"
33 .\" If the F register is >0, we'll generate index entries on stderr for
34 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
35 .\" entries marked with X<> in POD. Of course, you'll have to process the
36 .\" output yourself in some meaningful fashion.
37 .\"
38 .\" Avoid warning from groff about undefined register 'F'.
39 .de IX
40 ..
41 .nr rF 0
42 .if \n(.g .if rF .nr rF 1
43 .if (\n(rF:(\n(.g==0)) \{\
44 . if \nF \{\
45 . de IX
46 . tm Index:\\$1\t\\n%\t"\\$2"
47 ..
48 . if !\nF==2 \{\
49 . nr % 0
50 . nr F 2
51 . \}
52 . \}
53 .\}
54 .rr rF
55 .\" ========================================================================
56 .\"
57 .IX Title "SSL_SESSION_FREE 3SSL"
58 .TH SSL_SESSION_FREE 3SSL 2026-04-07 3.6.2 OpenSSL
59 .\" For nroff, turn off justification. Always turn off hyphenation; it makes
60 .\" way too many mistakes in technical documents.
61 .if n .ad l
62 .nh
63 .SH NAME
64 SSL_SESSION_new,
65 SSL_SESSION_dup,
66 SSL_SESSION_up_ref,
67 SSL_SESSION_free \- create, free and manage SSL_SESSION structures
68 .SH SYNOPSIS
69 .IX Header "SYNOPSIS"
70 .Vb 1
71 \& #include <openssl/ssl.h>
72 \&
73 \& SSL_SESSION *SSL_SESSION_new(void);
74 \& SSL_SESSION *SSL_SESSION_dup(const SSL_SESSION *src);
75 \& int SSL_SESSION_up_ref(SSL_SESSION *ses);
76 \& void SSL_SESSION_free(SSL_SESSION *session);
77 .Ve
78 .SH DESCRIPTION
79 .IX Header "DESCRIPTION"
80 \&\fBSSL_SESSION_new()\fR creates a new SSL_SESSION structure and returns a pointer to
81 it.
82 .PP
83 \&\fBSSL_SESSION_dup()\fR creates a new SSL_SESSION structure that is a copy of \fBsrc\fR.
84 The copy is not owned by any cache that \fBsrc\fR may have been in.
85 .PP
86 \&\fBSSL_SESSION_up_ref()\fR increments the reference count on the given SSL_SESSION
87 structure.
88 .PP
89 \&\fBSSL_SESSION_free()\fR decrements the reference count of \fBsession\fR and removes
90 the \fBSSL_SESSION\fR structure pointed to by \fBsession\fR and frees up the allocated
91 memory, if the reference count has reached 0.
92 If \fBsession\fR is NULL nothing is done.
93 .SH NOTES
94 .IX Header "NOTES"
95 SSL_SESSION objects are allocated, when a TLS/SSL handshake operation
96 is successfully completed. Depending on the settings, see
97 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
98 the SSL_SESSION objects are internally referenced by the SSL_CTX and
99 linked into its session cache. SSL objects may be using the SSL_SESSION object;
100 as a session may be reused, several SSL objects may be using one SSL_SESSION
101 object at the same time. It is therefore crucial to keep the reference
102 count (usage information) correct and not delete an SSL_SESSION object
103 that is still used, as this may lead to program failures due to
104 dangling pointers. These failures may also appear delayed, e.g.
105 when an SSL_SESSION object was completely freed as the reference count
106 incorrectly became 0, but it is still referenced in the internal
107 session cache and the cache list is processed during a
108 \&\fBSSL_CTX_flush_sessions\fR\|(3) operation.
109 .PP
110 \&\fBSSL_SESSION_free()\fR must only be called for SSL_SESSION objects, for
111 which the reference count was explicitly incremented (e.g.
112 by calling \fBSSL_get1_session()\fR, see \fBSSL_get_session\fR\|(3))
113 or when the SSL_SESSION object was generated outside a TLS handshake
114 operation, e.g. by using \fBd2i_SSL_SESSION\fR\|(3).
115 It must not be called on other SSL_SESSION objects, as this would cause
116 incorrect reference counts and therefore program failures.
117 .SH "RETURN VALUES"
118 .IX Header "RETURN VALUES"
119 SSL_SESSION_new returns a pointer to the newly allocated SSL_SESSION structure
120 or NULL on error.
121 .PP
122 SSL_SESSION_dup returns a pointer to the new copy or NULL on error.
123 .PP
124 SSL_SESSION_up_ref returns 1 on success or 0 on error.
125 .SH "SEE ALSO"
126 .IX Header "SEE ALSO"
127 \&\fBssl\fR\|(7), \fBSSL_get_session\fR\|(3),
128 \&\fBSSL_CTX_set_session_cache_mode\fR\|(3),
129 \&\fBSSL_CTX_flush_sessions\fR\|(3),
130 \&\fBd2i_SSL_SESSION\fR\|(3)
131 .SH HISTORY
132 .IX Header "HISTORY"
133 The \fBSSL_SESSION_dup()\fR function was added in OpenSSL 1.1.1.
134 .SH COPYRIGHT
135 .IX Header "COPYRIGHT"
136 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
137 .PP
138 Licensed under the Apache License 2.0 (the "License"). You may not use
139 this file except in compliance with the License. You can obtain a copy
140 in the file LICENSE in the source distribution or at
141 <https://www.openssl.org/source/license.html>.