Android_verify/lib/openssl/share/man/man3/SSL_new_stream.3ossl

.\" -*- mode: troff; coding: utf-8 -*-
.\" Automatically generated by Pod::Man 5.01 (Pod::Simple 3.43)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>.
.ie n \{\
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "SSL_NEW_STREAM 3ossl"
.TH SSL_NEW_STREAM 3ossl 2025-01-17 3.4.0 OpenSSL
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH NAME
SSL_new_stream, SSL_STREAM_FLAG_UNI, SSL_STREAM_FLAG_NO_BLOCK,
SSL_STREAM_FLAG_ADVANCE \- create a new locally\-initiated QUIC stream
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& #define SSL_STREAM_FLAG_UNI          (1U << 0)
\& #define SSL_STREAM_FLAG_NO_BLOCK     (1U << 1)
\& #define SSL_STREAM_FLAG_ADVANCE      (1U << 2)
\& SSL *SSL_new_stream(SSL *ssl, uint64_t flags);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_new_stream()\fR function, when passed a QUIC connection SSL object, creates
a new locally-initiated bidirectional or unidirectional QUIC stream and returns
the newly created QUIC stream SSL object.
.PP
If the \fBSSL_STREAM_FLAG_UNI\fR flag is passed, a unidirectional stream is
created; else a bidirectional stream is created.
.PP
To retrieve the stream ID of the newly created stream, use
\&\fBSSL_get_stream_id\fR\|(3).
.PP
It is the caller's responsibility to free the QUIC stream SSL object using
\&\fBSSL_free\fR\|(3). The lifetime of the QUIC connection SSL object must exceed that
of the QUIC stream SSL object; in other words, the QUIC stream SSL object must
be freed first.
.PP
Once a stream has been created using \fBSSL_new_stream()\fR, it may be used in the
normal way using \fBSSL_read\fR\|(3) and \fBSSL_write\fR\|(3).
.PP
This function can only be used to create stream objects for locally-initiated
streams. To accept incoming streams initiated by a peer, use
\&\fBSSL_accept_stream\fR\|(3).
.PP
Calling \fBSSL_new_stream()\fR if there is no default stream already present
inhibits the future creation of a default stream. See \fBopenssl\-quic\fR\|(7).
.PP
The creation of new streams is subject to flow control by the QUIC protocol. If
it is currently not possible to create a new locally initiated stream of the
specified type, a call to \fBSSL_new_stream()\fR will either block (if the connection
is configured in blocking mode) until a new stream can be created, or otherwise
return NULL.
.PP
This function operates in blocking mode if the QUIC connection SSL object is
configured in blocking mode (see \fBSSL_set_blocking_mode\fR\|(3)). It may also be
used in nonblocking mode on a connection configured in blocking mode by passing
the flag \fBSSL_STREAM_FLAG_NO_BLOCK\fR.
.PP
The flag \fBSSL_STREAM_FLAG_ADVANCE\fR may be used to create a QUIC stream SSL
object even if a new QUIC stream cannot yet be opened due to flow control. The
caller may begin to use the new stream and fill the write buffer of the stream
by calling \fBSSL_write\fR\|(3). However, no actual stream data (or QUIC frames
regarding the stream) will be sent until QUIC flow control allows it. Any queued
data will be sent as soon as a peer permits it. There is no guarantee the stream
will be eventually created; for example, the connection could fail, or a peer
might simply decide never to increase the number of allowed streams for the
remainder of the connection lifetime.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_new_stream()\fR returns a new stream object, or NULL on error.
.PP
This function fails if called on a QUIC stream SSL object or on a non-QUIC SSL
object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_accept_stream\fR\|(3), \fBSSL_free\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
\&\fBSSL_new_stream()\fR was added in OpenSSL 3.2.
.SH COPYRIGHT
.IX Header "COPYRIGHT"
Copyright 2002\-2023 The OpenSSL Project Authors. All Rights Reserved.
.PP
Licensed under the Apache License 2.0 (the "License").  You may not use
this file except in compliance with the License.  You can obtain a copy
in the file LICENSE in the source distribution or at
<https://www.openssl.org/source/license.html>.