SSL_GET_STREAM_READ_STATE(3SSL)

📦
version 4.0.3 · 6 versions
, in ubuntu stonking

💖 SSL_GET_STREAM_READ_STATE 💖 — no wait bestie, it's SSL_GET_STREAM_READ_STATE(3SSL) and it's the OpenSSL manual page for peeking at your QUIC stream's state 👀

okay so. real talk. you ever made a QUIC stream and you're just sitting there like... girl. what are you doing. are you okay. did we finish. did someone reset you. did the WHOLE CONNECTION die 😭

that's this page. it's the vibe check for your stream. 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 💅

🌸 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 your two little gossips — one tells you about the receiving half of a QUIC stream, the other tells you about the sending half. respectively, obviously 💅

They both hand you back ONE of these values, and every single one is a whole mood:

  • SSL_STREAM_STATE_NONE — bestie you called this on something that is NOT a QUIC SSL object, or on a QUIC connection SSL object that has no default stream attached. nothing to report. empty. void. 💀
  • SSL_STREAM_STATE_OK — the stream hasn't been concluded and it's still healthy! thriving! hydrated! ✨
  • SSL_STREAM_STATE_WRONG_DIR — you asked in the wrong direction, oops 🙈. This comes back if SSL_get_stream_read_state() gets called on a locally-initiated (and therefore send-only) unidirectional stream, or, flip it, if SSL_get_stream_write_state() gets called on a remotely-initiated (and therefore receive-only) unidirectional stream. it's giving "ma'am this is a Wendy's".
  • SSL_STREAM_STATE_FINISHED — we're done here, periodt.
    • For SSL_get_stream_read_state(): the remote peer signalled the end of the receiving part of the stream. ⚠️ note that there may still be residual data available to read via SSL_read(3) even when you get this state back — so don't you dare skip the leftovers.
    • For SSL_get_stream_write_state(): your local app concluded the stream using SSL_stream_conclude(3). Future SSL_write(3) calls will not succeed. it's over babe.
  • SSL_STREAM_STATE_RESET_LOCAL — the applicable stream part got reset by the local application. you did this. look at you.
    • For SSL_get_stream_read_state(): 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 grab any residual data that remains to be read by calling SSL_read(3).
    • For SSL_get_stream_write_state(): 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. 😭
    • When you get this value, the application error code that 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_RESET_REMOTE — the applicable stream part got reset by the remote peer. not you. them. 🫵
    • 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.
    • 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. 💀
    • When you get this value, the application error code that 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 the stream belongs to got closed. 🪦 You can get the tea 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 a fun little fact: SSL_get_stream_read_state() will return this state if and only if SSL_get_stream_write_state() will also return this state. they're matching. iconic. ✨

SSL_get_stream_read_error_code() and SSL_get_stream_write_error_code() hand you the application error code that was signalled during non-normal termination of the receiving or sending parts of a stream, respectively. On success, that application error code gets written to app_error_code. 📝

🎀 NOTES 🎀

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. 😔

However! You can obtain the overall error code associated with the connection closure using SSL_get_conn_close_info(3). slay.

🔥 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.

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, was still healthy at the time of connection closure, if called on a stream for which the respective stream part does not exist (e.g. on a unidirectional stream), or if called on a non-QUIC object or a QUIC connection SSL object without a default stream attached. messy. 💅

🌈 SEE ALSO 🌈

⭐ HISTORY ⭐

These functions were added in OpenSSL 3.2. newcomers but they 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>.

and that's the whole page bestie!! 🫶 this was OpenSSL 4.0.3, dated 2026-09-29, and you can find it filed under SSL_GET_STREAM_READ_STATE(3SSL) 💖 go check your stream states, drink some water, and remember: residual data might still be waiting for you even after FINISHED. no cap. 🧚✨

📦 where this page comes from