Debian Codegraph @

upstream/debian-unstable/man3/SSL_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_FREE 3SSL"
58 .TH SSL_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_free \- free an allocated SSL structure
65 .SH SYNOPSIS
66 .IX Header "SYNOPSIS"
67 .Vb 1
68 \& #include <openssl/ssl.h>
69 \&
70 \& void SSL_free(SSL *ssl);
71 .Ve
72 .SH DESCRIPTION
73 .IX Header "DESCRIPTION"
74 \&\fBSSL_free()\fR decrements the reference count of \fBssl\fR, and removes the SSL
75 structure pointed to by \fBssl\fR and frees up the allocated memory if the
76 reference count has reached 0.
77 If \fBssl\fR is NULL nothing is done.
78 .SH NOTES
79 .IX Header "NOTES"
80 \&\fBSSL_free()\fR also calls the \fBfree()\fRing procedures for indirectly affected items, if
81 applicable: the buffering BIO, the read and write BIOs,
82 cipher lists specially created for this \fBssl\fR, the \fBSSL_SESSION\fR.
83 Do not explicitly free these indirectly freed up items before or after
84 calling \fBSSL_free()\fR, as trying to free things twice may lead to program
85 failure.
86 .PP
87 The ssl session has reference counts from two users: the SSL object, for
88 which the reference count is removed by \fBSSL_free()\fR and the internal
89 session cache. If the session is considered bad, because
90 \&\fBSSL_shutdown\fR\|(3) was not called for the connection
91 and \fBSSL_set_shutdown\fR\|(3) was not used to set the
92 SSL_SENT_SHUTDOWN state, the session will also be removed
93 from the session cache as required by RFC2246.
94 .PP
95 When used to free a QUIC stream SSL object, the respective sending and receiving
96 parts of the stream are reset unless those parts have already been concluded
97 normally:
98 .IP \(bu 4
99 If the stream has a sending part (in other words, if it is bidirectional or a
100 locally-initiated unidirectional stream) and that part has not been concluded
101 via a call to \fBSSL_stream_conclude\fR\|(3) or \fBSSL_stream_reset\fR\|(3) on the QUIC
102 stream SSL object, a call to \fBSSL_free()\fR automatically resets the sending part of
103 the stream as though \fBSSL_stream_reset\fR\|(3) were called with a QUIC application
104 error code of 0.
105 .IP \(bu 4
106 If the stream has a receiving part (in other words, if it is bidirectional or a
107 remotely-initiated unidirectional stream), and the peer has not yet concluded
108 that part of the stream normally (such as via a call to
109 \&\fBSSL_stream_conclude\fR\|(3) on its own end), a call to \fBSSL_free()\fR automatically
110 requests the reset of the receiving part of the stream using a QUIC STOP_SENDING
111 frame with a QUIC application error code of 0. Note that as per the QUIC
112 protocol, this will automatically cause the peer to reset that part of the
113 stream in turn (which is its sending part).
114 .PP
115 A QUIC stream SSL object maintains a reference to a QUIC connection SSL object
116 internally, therefore a QUIC stream SSL object and its parent QUIC connection
117 SSL object can be freed in either order.
118 .SH "RETURN VALUES"
119 .IX Header "RETURN VALUES"
120 \&\fBSSL_free()\fR does not provide diagnostic information.
121 .PP
122 \&\fBSSL_new\fR\|(3), \fBSSL_clear\fR\|(3),
123 \&\fBSSL_shutdown\fR\|(3), \fBSSL_set_shutdown\fR\|(3),
124 \&\fBssl\fR\|(7)
125 .SH COPYRIGHT
126 .IX Header "COPYRIGHT"
127 Copyright 2000\-2023 The OpenSSL Project Authors. All Rights Reserved.
128 .PP
129 Licensed under the Apache License 2.0 (the "License"). You may not use
130 this file except in compliance with the License. You can obtain a copy
131 in the file LICENSE in the source distribution or at
132 <https://www.openssl.org/source/license.html>.