SSL_GET_STREAM_READ_STATE(3ossl)

📦 version 15.1, in freebsd 15.1

💅 SSL_GET_STREAM_READ_STATE(3ossl) — aka the OpenSSL glow-up for QUIC stream states 🦋

okay bestie, sit down, grab your matcha 🍓 — we're talking about the <openssl/ssl.h> girlies that let you peek at what a QUIC stream is actually going through. This is OpenSSL manual page energy, but make it group chat. Let's go ✨

🌸 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 — get QUIC stream state. periodt 👑

🎀 SYNOPSIS 🎀

Like, here's the vibe check in code form:

#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 functions that tell you the overall state of the receiving part and the sending part of a QUIC stream respectively. Two parts, two functions, no cap 🫶

Both of them return exactly one of these iconic values:

💜 The State Constants (the main characters)

  • 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 doesn't have a default stream attached. Basically: nothing here babe 🙈
  • SSL_STREAM_STATE_OK — this is the healthy one! It means the stream hasn't been concluded and is still doing fine. We love a stable queen 💖
  • SSL_STREAM_STATE_WRONG_DIR — dir as in direction, bestie, not your fave artist. You get this if SSL_get_stream_read_state() gets called on a locally-initiated (and thus send-only) unidirectional stream — or, conversely, if SSL_get_stream_write_state() gets called on a remotely-initiated (and thus receive-only) unidirectional stream. Wrong door, wrong vibe, wrong direction 💀
  • SSL_STREAM_STATE_FINISHED — ok so this one means something different depending on who's asking:
    • For SSL_get_stream_read_state(): the remote peer has signalled the end of the receiving part of the stream. Important note though — there may still be residual data available to read via SSL_read(3) even when this state is returned. So don't just dip, check for leftovers 🍓
    • For SSL_get_stream_write_state(): the local application has concluded the stream using SSL_stream_conclude(3). Future SSL_write(3) calls will not succeed. The door is closed, the light is off, we're done here ✌️
  • SSL_STREAM_STATE_RESET_LOCAL — the applicable stream part got reset by the local application. Breaking it down:
    • 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). Maybe. Maybe not. Schrödinger's buffer 😭
    • 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. byeee 💅
    • Whenever this value is returned, you can grab the application error code that was signalled by calling SSL_get_stream_read_error_code() or SSL_get_stream_write_error_code() — whichever one is appropriate, iykyk 🌈
  • SSL_STREAM_STATE_RESET_REMOTE — the applicable stream part got reset by the remote peer. Two flavours:
    • For SSL_get_stream_read_state(): 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. Rude, but ok 🫠
    • For SSL_get_stream_write_state(): 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 stop, so we stop 🛑
    • 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 ✨
  • SSL_STREAM_STATE_CONN_CLOSED — the QUIC connection that this stream belongs to got closed. You can obtain info 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 a fun little symmetry: SSL_get_stream_read_state() will return this state if and only if SSL_get_stream_write_state() will also return this state. Matching outfits, adorable 👯‍♀️

🧚 The Error Code Functions

SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() provide the application error code which 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. Look at that little pointer pop off 💅

🦋 NOTES 🦋

okay so important plot twist: if a QUIC connection is closed, the stream state for all streams transitions to SSL_STREAM_STATE_CONN_CLOSED, but 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. Yeah. Group project energy, nobody gets individual credit 😭

However! You can obtain the overall error code associated with the connection closure using SSL_get_conn_close_info(3). So like, there is a receipt, just at the connection level 👑

⭐ RETURN VALUES ⭐

SSL_get_stream_read_state() and SSL_get_stream_write_state() return one of the SSL_STREAM_STATE values. If called on a non-QUIC SSL object, or a QUIC connection SSL object without a default stream, SSL_STREAM_STATE_NONE is returned. Simple as that ✨

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,
  • it was called on a stream for which the respective stream part does not exist (e.g. on a unidirectional stream),
  • or it was called on a non-QUIC object or a QUIC connection SSL object without a default stream attached.

Ma'am, that's a lot of reasons to get a -1. Respect the list 🙈

🔥 SEE ALSO 🔥

go read those next, bestie, they're all linked lore 🧚‍♀️

👑 HISTORY 👑

These functions were added in OpenSSL 3.2. New era, new QUIC stream state functions, we ate 🌈

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>. Legal girlies, this one's for you 🫶

and that's the whole page, no notes 💅

kisses, this was OpenSSL 3.5.6, dated 2026-04-07 — SSL_GET_STREAM_READ_STATE(3ossl), out 🎀✨

📦 where this page comes from