Debian Codegraph @

upstream/debian-unstable/man3/SSL_new_stream.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_NEW_STREAM 3SSL"
58 .TH SSL_NEW_STREAM 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_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK,
65 SSL_STREAM_FLAG_ADVANCE \- create a new locally\-initiated QUIC stream
66 .SH SYNOPSIS
67 .IX Header "SYNOPSIS"
68 .Vb 1
69 \& #include <openssl/ssl.h>
70 \&
71 \& #define SSL_STREAM_FLAG_UNI (1U << 0)
72 \& #define SSL_STREAM_FLAG_NO_BLOCK (1U << 1)
73 \& #define SSL_STREAM_FLAG_ADVANCE (1U << 2)
74 \& SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
75 .Ve
76 .SH DESCRIPTION
77 .IX Header "DESCRIPTION"
78 The \fBSSL_new_stream()\fR function, when passed a QUIC connection SSL object, creates
79 a new locally-initiated bidirectional or unidirectional QUIC stream and returns
80 the newly created QUIC stream SSL object.
81 .PP
82 If the \fBSSL_STREAM_FLAG_UNI\fR flag is passed, a unidirectional stream is
83 created; else a bidirectional stream is created.
84 .PP
85 To retrieve the stream ID of the newly created stream, use
86 \&\fBSSL_get_stream_id\fR\|(3).
87 .PP
88 It is the caller's responsibility to free the QUIC stream SSL object using
89 \&\fBSSL_free\fR\|(3). The lifetime of the QUIC connection SSL object must exceed that
90 of the QUIC stream SSL object; in other words, the QUIC stream SSL object must
91 be freed first.
92 .PP
93 Once a stream has been created using \fBSSL_new_stream()\fR, it may be used in the
94 normal way using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3).
95 .PP
96 This function can only be used to create stream objects for locally-initiated
97 streams. To accept incoming streams initiated by a peer, use
98 \&\fBSSL_accept_stream\fR\|(3).
99 .PP
100 Calling \fBSSL_new_stream()\fR if there is no default stream already present
101 inhibits the future creation of a default stream. See \fBopenssl\-quic\fR\|(7).
102 .PP
103 The creation of new streams is subject to flow control by the QUIC protocol. If
104 it is currently not possible to create a new locally initiated stream of the
105 specified type, a call to \fBSSL_new_stream()\fR will either block (if the connection
106 is configured in blocking mode) until a new stream can be created, or otherwise
107 return NULL.
108 .PP
109 This function operates in blocking mode if the QUIC connection SSL object is
110 configured in blocking mode (see \fBSSL_set_blocking_mode\fR\|(3)). It may also be
111 used in nonblocking mode on a connection configured in blocking mode by passing
112 the flag \fBSSL_STREAM_FLAG_NO_BLOCK\fR.
113 .PP
114 The flag \fBSSL_STREAM_FLAG_ADVANCE\fR may be used to create a QUIC stream SSL
115 object even if a new QUIC stream cannot yet be opened due to flow control. The
116 caller may begin to use the new stream and fill the write buffer of the stream
117 by calling \fBSSL_write\fR\|(3). However, no actual stream data (or QUIC frames
118 regarding the stream) will be sent until QUIC flow control allows it. Any queued
119 data will be sent as soon as a peer permits it. There is no guarantee the stream
120 will be eventually created; for example, the connection could fail, or a peer
121 might simply decide never to increase the number of allowed streams for the
122 remainder of the connection lifetime.
123 .SH "RETURN VALUES"
124 .IX Header "RETURN VALUES"
125 \&\fBSSL_new_stream()\fR returns a new stream object, or NULL on error.
126 .PP
127 This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL
128 object.
129 .PP
130 \&\fBSSL_new_stream()\fR may also fail if the underlying connection has reached the
131 maximum stream count, based on the \fBmax_streams_bidi\fR or \fBmax_streams_uni\fR
132 transport parameter values negotiated with the peer. In this event the NULL
133 return will be accompanied by an error on the error stack (obtainable via
134 \&\fBERR_get_error()\fR), which will contain a reason code of
135 \&\fBSSL_R_STREAM_COUNT_LIMITED\fR. When this error is encountered, the operation
136 may be retried. It is recommended that, prior to retry, the error stack be
137 cleared via a call to \fBERR_clear_error()\fR, and that the TLS state machine be
138 activated via a call to \fBSSL_handle_events()\fR to process any potential updates
139 from the server allowing additional streams to be created.
140 .SH "SEE ALSO"
141 .IX Header "SEE ALSO"
142 \&\fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3)
143 .SH HISTORY
144 .IX Header "HISTORY"
145 \&\fBSSL_new_stream()\fR was added in OpenSSL 3.2.
146 .SH COPYRIGHT
147 .IX Header "COPYRIGHT"
148 Copyright 2002\-2025 The OpenSSL Project Authors. All Rights Reserved.
149 .PP
150 Licensed under the Apache License 2.0 (the "License"). You may not use
151 this file except in compliance with the License. You can obtain a copy
152 in the file LICENSE in the source distribution or at
153 <https://www.openssl.org/source/license.html>.