Debian Codegraph @

upstream/debian-unstable/man3/SSL_get_stream_read_state.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_GET_STREAM_READ_STATE 3SSL"
58 .TH SSL_GET_STREAM_READ_STATE 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_get_stream_read_state, SSL_get_stream_write_state,
65 SSL_get_stream_read_error_code, SSL_get_stream_write_error_code,
66 SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR,
67 SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL,
68 SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED \- get QUIC stream
69 state
70 .SH SYNOPSIS
71 .IX Header "SYNOPSIS"
72 .Vb 1
73 \& #include <openssl/ssl.h>
74 \&
75 \& #define SSL_STREAM_STATE_NONE
76 \& #define SSL_STREAM_STATE_OK
77 \& #define SSL_STREAM_STATE_WRONG_DIR
78 \& #define SSL_STREAM_STATE_FINISHED
79 \& #define SSL_STREAM_STATE_RESET_LOCAL
80 \& #define SSL_STREAM_STATE_RESET_REMOTE
81 \& #define SSL_STREAM_STATE_CONN_CLOSED
82 \&
83 \& int SSL_get_stream_read_state(SSL *ssl);
84 \& int SSL_get_stream_write_state(SSL *ssl);
85 \&
86 \& int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
87 \& int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);
88 .Ve
89 .SH DESCRIPTION
90 .IX Header "DESCRIPTION"
91 \&\fBSSL_get_stream_read_state()\fR and \fBSSL_get_stream_write_state()\fR retrieve the
92 overall state of the receiving and sending parts of a QUIC stream, respectively.
93 .PP
94 They both return one of the following values:
95 .IP \fBSSL_STREAM_STATE_NONE\fR 4
96 .IX Item "SSL_STREAM_STATE_NONE"
97 This value is returned if called on a non-QUIC SSL object, or on a QUIC
98 connection SSL object without a default stream attached.
99 .IP \fBSSL_STREAM_STATE_OK\fR 4
100 .IX Item "SSL_STREAM_STATE_OK"
101 This value is returned on a stream which has not been concluded and remains
102 healthy.
103 .IP \fBSSL_STREAM_STATE_WRONG_DIR\fR 4
104 .IX Item "SSL_STREAM_STATE_WRONG_DIR"
105 This value is returned if \fBSSL_get_stream_read_state()\fR is called on a
106 locally-initiated (and thus send-only) unidirectional stream, or, conversely, if
107 \&\fBSSL_get_stream_write_state()\fR is called on a remotely-initiated (and thus
108 receive-only) unidirectional stream.
109 .IP \fBSSL_STREAM_STATE_FINISHED\fR 4
110 .IX Item "SSL_STREAM_STATE_FINISHED"
111 For \fBSSL_get_stream_read_state()\fR, this value is returned when the remote peer has
112 signalled the end of the receiving part of the stream. Note that there may still
113 be residual data available to read via \fBSSL_read\fR\|(3) when this state is
114 returned.
115 .Sp
116 For \fBSSL_get_stream_write_state()\fR, this value is returned when the local
117 application has concluded the stream using \fBSSL_stream_conclude\fR\|(3). Future
118 \&\fBSSL_write\fR\|(3) calls will not succeed.
119 .IP \fBSSL_STREAM_STATE_RESET_LOCAL\fR 4
120 .IX Item "SSL_STREAM_STATE_RESET_LOCAL"
121 This value is returned when the applicable stream part was reset by the local
122 application.
123 .Sp
124 For \fBSSL_get_stream_read_state()\fR, this means that the receiving part of the
125 stream was aborted using a locally transmitted QUIC \fBSTOP_SENDING\fR frame. It
126 may or may not still be possible to obtain any residual data which remains to be
127 read by calling \fBSSL_read\fR\|(3).
128 .Sp
129 For \fBSSL_get_stream_write_state()\fR, this means that the sending part of the stream
130 was aborted, for example because the application called \fBSSL_stream_reset\fR\|(3),
131 or because a QUIC stream SSL object with an un-concluded sending part was freed
132 using \fBSSL_free\fR\|(3). Calls to \fBSSL_write\fR\|(3) will fail.
133 .Sp
134 When this value is returned, the application error code which was signalled can
135 be obtained by calling \fBSSL_get_stream_read_error_code()\fR or
136 \&\fBSSL_get_stream_write_error_code()\fR as appropriate.
137 .IP \fBSSL_STREAM_STATE_RESET_REMOTE\fR 4
138 .IX Item "SSL_STREAM_STATE_RESET_REMOTE"
139 This value is returned when the applicable stream part was reset by the remote
140 peer.
141 .Sp
142 For \fBSSL_get_stream_read_state()\fR, this means that the peer sent a QUIC
143 \&\fBRESET_STREAM\fR frame for the receiving part of the stream; the receiving part
144 of the stream was logically aborted by the peer.
145 .Sp
146 For \fBSSL_get_stream_write_state()\fR, this means that the peer sent a QUIC
147 \&\fBSTOP_SENDING\fR frame for the sending part of the stream; the peer has indicated
148 that it does not wish to receive further data on the sending part of the stream.
149 Calls to \fBSSL_write\fR\|(3) will fail.
150 .Sp
151 When this value is returned, the application error code which was signalled can
152 be obtained by calling \fBSSL_get_stream_read_error_code()\fR or
153 \&\fBSSL_get_stream_write_error_code()\fR as appropriate.
154 .IP \fBSSL_STREAM_STATE_CONN_CLOSED\fR 4
155 .IX Item "SSL_STREAM_STATE_CONN_CLOSED"
156 The QUIC connection to which the stream belongs was closed. You can obtain
157 information about the circumstances of this closure using
158 \&\fBSSL_get_conn_close_info\fR\|(3). There may still be residual data available to
159 read via \fBSSL_read\fR\|(3) when this state is returned. Calls to \fBSSL_write\fR\|(3)
160 will fail. \fBSSL_get_stream_read_state()\fR will return this state if and only if
161 \&\fBSSL_get_stream_write_state()\fR will also return this state.
162 .PP
163 \&\fBSSL_get_stream_read_error_code()\fR and \fBSSL_get_stream_write_error_code()\fR provide
164 the application error code which was signalled during non-normal termination of
165 the receiving or sending parts of a stream, respectively. On success, the
166 application error code is written to \fI*app_error_code\fR.
167 .SH NOTES
168 .IX Header "NOTES"
169 If a QUIC connection is closed, the stream state for all streams transitions to
170 \&\fBSSL_STREAM_STATE_CONN_CLOSED\fR, but no application error code can be retrieved
171 using \fBSSL_get_stream_read_error_code()\fR or \fBSSL_get_stream_write_error_code()\fR, as
172 the QUIC connection closure process does not cause an application error code to
173 be associated with each individual stream still existing at the time of
174 connection closure. However, you can obtain the overall error code associated
175 with the connection closure using \fBSSL_get_conn_close_info\fR\|(3).
176 .SH "RETURN VALUES"
177 .IX Header "RETURN VALUES"
178 \&\fBSSL_get_stream_read_state()\fR and \fBSSL_get_stream_write_state()\fR return one of the
179 \&\fBSSL_STREAM_STATE\fR values. If called on a non-QUIC SSL object, or a QUIC
180 connection SSL object without a default stream, \fBSSL_STREAM_STATE_NONE\fR is
181 returned.
182 .PP
183 \&\fBSSL_get_stream_read_error_code()\fR and \fBSSL_get_stream_write_error_code()\fR return 1
184 on success and 0 if the stream was terminated normally. They return \-1 on error,
185 for example if the stream is still healthy, was still healthy at the time of
186 connection closure, if called on a stream for which the respective stream part
187 does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC
188 object or a QUIC connection SSL object without a default stream attached.
189 .SH "SEE ALSO"
190 .IX Header "SEE ALSO"
191 \&\fBSSL_stream_conclude\fR\|(3), \fBSSL_stream_reset\fR\|(3), \fBSSL_new_stream\fR\|(3),
192 \&\fBSSL_accept_stream\fR\|(3), \fBSSL_get_conn_close_info\fR\|(3)
193 .SH HISTORY
194 .IX Header "HISTORY"
195 These functions were added in OpenSSL 3.2.
196 .SH COPYRIGHT
197 .IX Header "COPYRIGHT"
198 Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
199 .PP
200 Licensed under the Apache License 2.0 (the "License"). You may not use
201 this file except in compliance with the License. You can obtain a copy
202 in the file LICENSE in the source distribution or at
203 <https://www.openssl.org/source/license.html>.