SSL_GET_STREAM_READ_STATE(3ossl)

📦 version 3.5.0, in opensuse-leap 16.0

💅 SSL_GET_STREAM_READ_STATE(3ossl) — your QUIC stream vibes check

okay so bestie, this page is SSL_GET_STREAM_READ_STATE(3ossl) from the OpenSSL fam, and it's literally all about finding out how your QUIC stream is doing emotionally 🫶. Like, is it fine? Is it done? Did somebody reset it? We're gonna find out. No cap.

✨ NAME ✨

SSL_get_stream_read_state, SSL_get_stream_write_state, SSL_get_stream_read_error_code, SSL_get_stream_write_error_code, SSL_STREAM_STATE_NONE, SSL_STREAM_STATE_OK, SSL_STREAM_STATE_WRONG_DIR, SSL_STREAM_STATE_FINISHED, SSL_STREAM_STATE_RESET_LOCAL, SSL_STREAM_STATE_RESET_REMOTE, SSL_STREAM_STATE_CONN_CLOSED — all of these together are the "get QUIC stream state" squad 👑

🎀 SYNOPSIS 🎀

#include <openssl/ssl.h>

#define SSL_STREAM_STATE_NONE
#define SSL_STREAM_STATE_OK
#define SSL_STREAM_STATE_WRONG_DIR
#define SSL_STREAM_STATE_FINISHED
#define SSL_STREAM_STATE_RESET_LOCAL
#define SSL_STREAM_STATE_RESET_REMOTE
#define SSL_STREAM_STATE_CONN_CLOSED

int SSL_get_stream_read_state(SSL *ssl);
int SSL_get_stream_write_state(SSL *ssl);

int SSL_get_stream_read_error_code(SSL *ssl, uint64_t *app_error_code);
int SSL_get_stream_write_error_code(SSL *ssl, uint64_t *app_error_code);

🌸 DESCRIPTION 🌸

So SSL_get_stream_read_state() and SSL_get_stream_write_state() are the two besties that tell you the overall state of the receiving part and the sending part of a QUIC stream, respectively. Reading side, writing side, very much a his-and-hers situation 💖.

They both return exactly one of these values:

  • SSL_STREAM_STATE_NONE — you get this one if you called it on a non-QUIC SSL object, or on a QUIC connection SSL object that has no default stream attached. Basically "girl, there's no stream here" 💀.
  • SSL_STREAM_STATE_OK — this is the healthy-glow-up state. Returned on a stream that hasn't been concluded and is still vibing, healthy, living its truth ✨.
  • SSL_STREAM_STATE_WRONG_DIR — the "wrong chat, wrong direction" state 🙈. You get this if SSL_get_stream_read_state() is called on a locally-initiated (and thus send-only) unidirectional stream, or, conversely, if SSL_get_stream_write_state() is called on a remotely-initiated (and thus receive-only) unidirectional stream. Like trying to read a stream that only writes. Embarrassing.
  • SSL_STREAM_STATE_FINISHED — the "we're done here, iconic" state 🎬.
    • For SSL_get_stream_read_state(), you get this when the remote peer has signalled the end of the receiving part of the stream. ⚠️ Important tea: there may still be residual data available to read via SSL_read(3) when this state is returned. So don't ghost the buffer just yet.
    • For SSL_get_stream_write_state(), you get this when the local application has concluded the stream using SSL_stream_conclude(3). Future SSL_write(3) calls will not succeed. Periodt.
  • SSL_STREAM_STATE_RESET_LOCAL — the applicable stream part was reset by you, the local application 😤.
    • For SSL_get_stream_read_state(), this means the receiving part of the stream was aborted using a locally transmitted QUIC STOP_SENDING frame. It may or may not still be possible to obtain any residual data which remains to be read by calling SSL_read(3). Roll the dice, bestie.
    • For SSL_get_stream_write_state(), this means the sending part of the stream was aborted, for example because the application called SSL_stream_reset(3), or because a QUIC stream SSL object with an un-concluded sending part was freed using SSL_free(3). Calls to SSL_write(3) will fail. Straight up no ❌.
    • When this value is returned, the application error code which was signalled can be obtained by calling SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code() as appropriate. Receipts available 💅.
  • SSL_STREAM_STATE_RESET_REMOTE — the applicable stream part was reset by the remote peer. Not you. Them. 😭
    • For SSL_get_stream_read_state(), this means the peer sent a QUIC RESET_STREAM frame for the receiving part of the stream; the receiving part of the stream was logically aborted by the peer.
    • For SSL_get_stream_write_state(), this means the peer sent a QUIC STOP_SENDING frame for the sending part of the stream; the peer has indicated that it does not wish to receive further data on the sending part of the stream. Calls to SSL_write(3) will fail. They said no thanks ✋.
    • When this value is returned, the application error code which was signalled can be obtained by calling SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code() as appropriate. Same receipts situation.
  • SSL_STREAM_STATE_CONN_CLOSED — the whole QUIC connection that the stream belongs to was closed. 💀 You can obtain information about the circumstances of this closure using SSL_get_conn_close_info(3). There may still be residual data available to read via SSL_read(3) when this state is returned. Calls to SSL_write(3) will fail. And here's the matching-set detail: SSL_get_stream_read_state() will return this state if and only if SSL_get_stream_write_state() will also return this state. Twinning fr fr 👯.

Then there's SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code(), which provide the application error code that was signalled during non-normal termination of the receiving or sending parts of a stream, respectively. On success, the application error code is written to *app_error_code. Cute.

🦋 NOTES 🦋

Okay so if a QUIC connection is closed, the stream state for all streams transitions to SSL_STREAM_STATE_CONN_CLOSED, but — and this is the key part, don't miss it — no application error code can be retrieved using SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code(), because the QUIC connection closure process does not cause an application error code to be associated with each individual stream still existing at the time of connection closure. Like, the group chat got deleted, you're not getting individual read receipts 😔.

However! You can obtain the overall error code associated with the connection closure using SSL_get_conn_close_info(3). So there's still a way to know what happened. Slay.

⭐ RETURN VALUES ⭐

SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the SSL_STREAM_STATE values. And reminder, bestie: if called on a non-QUIC SSL object, or a QUIC connection SSL object without a default stream, SSL_STREAM_STATE_NONE is returned. Very consistent of them 💜.

SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() return 1 on success and 0 if the stream was terminated normally. They return -1 on error — for example if:

  • the stream is still healthy,
  • it was still healthy at the time of connection closure,
  • you called it on a stream for which the respective stream part does not exist (e.g. on a unidirectional stream),
  • or you called it on a non-QUIC object, or a QUIC connection SSL object without a default stream attached.

So 1 = yay, 0 = ended normally, -1 = nope 🙅.

🌈 SEE ALSO 🌈

SSL_stream_conclude(3), SSL_stream_reset(3), SSL_new_stream(3), SSL_accept_stream(3), SSL_get_conn_close_info(3) — go read these too, they're all connected, iykyk 👑

🍓 HISTORY 🍓

These functions were added in OpenSSL 3.2. Newer than the vibe, honestly.

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 <https://www.openssl.org/source/license.html>.

okay that's the whole page, go forth and check your stream states, bestie 🧚✨

Version 3.5.0, dated 2026-09-25 — that's the SSL_GET_STREAM_READ_STATE(3ossl) moment, mwah 💋🎀

📦 where this page comes from