diff options
Diffstat (limited to 'doc/man3/SSL_accept_stream.pod')
-rw-r--r-- | doc/man3/SSL_accept_stream.pod | 74 |
1 files changed, 74 insertions, 0 deletions
diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod new file mode 100644 index 0000000000..55c1868323 --- /dev/null +++ b/doc/man3/SSL_accept_stream.pod @@ -0,0 +1,74 @@ +=pod + +=head1 NAME + +SSL_accept_stream, SSL_get_accept_stream_queue_len, SSL_ACCEPT_STREAM_NO_BLOCK - +accept an incoming QUIC stream from a QUIC peer + +=head1 SYNOPSIS + + #include <openssl/ssl.h> + + #define SSL_ACCEPT_STREAM_NO_BLOCK + + SSL *SSL_accept_stream(SSL *ssl, uint64_t flags); + + size_t SSL_get_accept_stream_queue_len(SSL *ssl); + +=head1 DESCRIPTION + +The SSL_accept_stream() function attempts to dequeue an incoming stream from the +given QUIC connection SSL object and returns the newly allocated QUIC stream SSL +object. + +If the queue of incoming streams is empty, this function returns NULL (in +nonblocking mode) or waits for an incoming stream (in blocking mode). This +function may still return NULL in blocking mode, for example if the underlying +connection is terminated. + +The caller is responsible for managing the lifetime of the returned QUIC stream +SSL object. The lifespan of the parent QUIC connection SSL object must exceed +that of the QUIC stream SSL object; that is, the stream object must be freed +first, using L<SSL_free(3)>. + +This function will block if the QUIC connection SSL object is configured in +blocking mode (see L<SSL_set_blocking_mode(3)>), but this may be bypassed by +passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in B<flags>. If this flag is set, +this function never blocks. + +SSL_accept_stream_queue_len() returns the number of incoming streams currently +waiting in the accept queue. It is intended for informational use only, as this +number may change between a call to it and a subsequent call to +SSL_accept_stream(), due to SSL_accept_stream() calls by other threads. + +Depending on whether default stream functionality is being used, it may be +necessary to explicitly configure the incoming stream rejection policy before +streams can be accepted; see L<SSL_set_incoming_stream_reject_policy(3)>. + +=head1 RETURN VALUES + +SSL_accept_stream() returns a newly allocated QUIC stream SSL object, or NULL if +no new incoming streams are available, or if the connection has been terminated. + +SSL_get_accept_stream_queue_len() returns the number of incoming streams +currently waiting in the accept queue. + +=head1 SEE ALSO + +L<SSL_new_stream(3)>, L<SSL_set_blocking_mode(3)>, L<SSL_free(3)> + +=head1 HISTORY + +SSL_accept_stream() and SSL_get_accept_stream_queue_len() were added in OpenSSL +3.2. + +=head1 COPYRIGHT + +Copyright 2002-2023 The OpenSSL Project Authors. All Rights Reserved. + +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 +L<https://www.openssl.org/source/license.html>. + +=cut |