1=pod 2 3=head1 NAME 4 5SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK, 6SSL_STREAM_FLAG_ADVANCE - create a new locally-initiated QUIC stream 7 8=head1 SYNOPSIS 9 10 #include <openssl/ssl.h> 11 12 #define SSL_STREAM_FLAG_UNI (1U << 0) 13 #define SSL_STREAM_FLAG_NO_BLOCK (1U << 1) 14 #define SSL_STREAM_FLAG_ADVANCE (1U << 2) 15 SSL *SSL_new_stream(SSL *ssl, uint64_t flags); 16 17=head1 DESCRIPTION 18 19The SSL_new_stream() function, when passed a QUIC connection SSL object, creates 20a new locally-initiated bidirectional or unidirectional QUIC stream and returns 21the newly created QUIC stream SSL object. 22 23If the B<SSL_STREAM_FLAG_UNI> flag is passed, a unidirectional stream is 24created; else a bidirectional stream is created. 25 26To retrieve the stream ID of the newly created stream, use 27L<SSL_get_stream_id(3)>. 28 29It is the caller's responsibility to free the QUIC stream SSL object using 30L<SSL_free(3)>. The lifetime of the QUIC connection SSL object must exceed that 31of the QUIC stream SSL object; in other words, the QUIC stream SSL object must 32be freed first. 33 34Once a stream has been created using SSL_new_stream(), it may be used in the 35normal way using L<SSL_read(3)> and L<SSL_write(3)>. 36 37This function can only be used to create stream objects for locally-initiated 38streams. To accept incoming streams initiated by a peer, use 39L<SSL_accept_stream(3)>. 40 41Calling SSL_new_stream() if there is no default stream already present 42inhibits the future creation of a default stream. See L<openssl-quic(7)>. 43 44The creation of new streams is subject to flow control by the QUIC protocol. If 45it is currently not possible to create a new locally initiated stream of the 46specified type, a call to SSL_new_stream() will either block (if the connection 47is configured in blocking mode) until a new stream can be created, or otherwise 48return NULL. 49 50This function operates in blocking mode if the QUIC connection SSL object is 51configured in blocking mode (see L<SSL_set_blocking_mode(3)>). It may also be 52used in nonblocking mode on a connection configured in blocking mode by passing 53the flag B<SSL_STREAM_FLAG_NO_BLOCK>. 54 55The flag B<SSL_STREAM_FLAG_ADVANCE> may be used to create a QUIC stream SSL 56object even if a new QUIC stream cannot yet be opened due to flow control. The 57caller may begin to use the new stream and fill the write buffer of the stream 58by calling L<SSL_write(3)>. However, no actual stream data (or QUIC frames 59regarding the stream) will be sent until QUIC flow control allows it. Any queued 60data will be sent as soon as a peer permits it. There is no guarantee the stream 61will be eventually created; for example, the connection could fail, or a peer 62might simply decide never to increase the number of allowed streams for the 63remainder of the connection lifetime. 64 65=head1 RETURN VALUES 66 67SSL_new_stream() returns a new stream object, or NULL on error. 68 69This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL 70object. 71 72SSL_new_stream() may also fail if the underlying connection has reached the 73maximum stream count, based on the B<max_streams_bidi> or B<max_streams_uni> 74transport parameter values negotiated with the peer. In this event the NULL 75return will be accompanied by an error on the error stack (obtainable via 76ERR_get_error()), which will contain a reason code of 77B<SSL_R_STREAM_COUNT_LIMITED>. When this error is encountered, the operation 78may be retried. It is recommended that, prior to retry, the error stack be 79cleared via a call to ERR_clear_error(), and that the TLS state machine be 80activated via a call to SSL_handle_events() to process any potential updates 81from the server allowing additional streams to be created. 82 83=head1 SEE ALSO 84 85L<SSL_accept_stream(3)>, L<SSL_free(3)> 86 87=head1 HISTORY 88 89SSL_new_stream() was added in OpenSSL 3.2. 90 91=head1 COPYRIGHT 92 93Copyright 2002-2025 The OpenSSL Project Authors. All Rights Reserved. 94 95Licensed under the Apache License 2.0 (the "License"). You may not use 96this file except in compliance with the License. You can obtain a copy 97in the file LICENSE in the source distribution or at 98L<https://www.openssl.org/source/license.html>. 99 100=cut 101