.\" -*- 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_GET_CONN_CLOSE_INFO 3SSL"
.TH SSL_GET_CONN_CLOSE_INFO 3SSL 2024-04-04 3.2.2-dev 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_get_conn_close_info, SSL_CONN_CLOSE_FLAG_LOCAL,
SSL_CONN_CLOSE_FLAG_TRANSPORT \- get information about why a QUIC connection was
closed
.SH SYNOPSIS
.IX Header "SYNOPSIS"
.Vb 1
\& #include <openssl/ssl.h>
\&
\& #define SSL_CONN_CLOSE_FLAG_LOCAL
\& #define SSL_CONN_CLOSE_FLAG_TRANSPORT
\&
\& typedef struct ssl_conn_close_info_st {
\&     uint64_t error_code, frame_type;
\&     char     *reason;
\&     size_t   reason_len;
\&     uint32_t flags;
\& } SSL_CONN_CLOSE_INFO;
\&
\& int SSL_get_conn_close_info(SSL *ssl, SSL_CONN_CLOSE_INFO *info,
\&                             size_t info_len);
.Ve
.SH DESCRIPTION
.IX Header "DESCRIPTION"
The \fBSSL_get_conn_close_info()\fR function provides information about why and how a
QUIC connection was closed.
.PP
Connection closure information is written to \fI*info\fR, which must be non-NULL.
\&\fIinfo_len\fR must be set to \f(CWsizeof(*info)\fR.
.PP
The following fields are set:
.IP \fIerror_code\fR 4
.IX Item "error_code"
This is a 62\-bit QUIC error code. It is either a 62\-bit application error code
(if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR not set in \fIflags\fR) or a  62\-bit standard
QUIC transport error code (if \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set in
\&\fIflags\fR).
.IP \fIframe_type\fR 4
.IX Item "frame_type"
If \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set, this may be set to a QUIC frame type
number which caused the connection to be closed. It may also be set to 0 if no
frame type was specified as causing the connection to be closed. If
\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is not set, this is set to 0.
.IP \fIreason\fR 4
.IX Item "reason"
If non-NULL, this is intended to be a UTF\-8 textual string briefly describing
the reason for connection closure. The length of the reason string in bytes is
given in \fIreason_len\fR. While, if non-NULL, OpenSSL guarantees that this string
will be zero terminated, consider that this buffer may originate from the
(untrusted) peer and thus may also contain zero bytes elsewhere. Therefore, use
of \fIreason_len\fR is recommended.
.Sp
While it is intended as per the QUIC protocol that this be a UTF\-8 string, there
is no guarantee that this is the case for strings received from the peer.
.IP \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR 4
.IX Item "SSL_CONN_CLOSE_FLAG_LOCAL"
If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_LOCAL\fR set, connection closure was locally
triggered. This could be due to an application request (e.g. if
\&\fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR is unset), or (if
\&\fISSL_CONN_CLOSE_FLAG_TRANSPORT\fR is set) due to logic internal to the QUIC
implementation (for example, if the peer engages in a protocol violation, or an
idle timeout occurs).
.Sp
If unset, connection closure was remotely triggered.
.IP \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR 4
.IX Item "SSL_CONN_CLOSE_FLAG_TRANSPORT"
If \fIflags\fR has \fBSSL_CONN_CLOSE_FLAG_TRANSPORT\fR set, connection closure was
triggered for QUIC protocol reasons. Otherwise, connection closure was triggered
by the local or remote application.
.SH "RETURN VALUES"
.IX Header "RETURN VALUES"
\&\fBSSL_get_conn_close_info()\fR returns 1 on success and 0 on failure. This function
fails if called on a QUIC connection SSL object which has not yet been
terminated. It also fails if called on a QUIC stream SSL object or a non-QUIC
SSL object.
.SH "SEE ALSO"
.IX Header "SEE ALSO"
\&\fBSSL_shutdown_ex\fR\|(3)
.SH HISTORY
.IX Header "HISTORY"
This function 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>.