QUIC MSST: Documentation fixes

Reviewed-by: Matt Caswell <matt@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/20765)

diff --git a/doc/man3/SSL_accept_stream.pod b/doc/man3/SSL_accept_stream.pod
index 430b3dd3644c976d3da5528885e01f6c31c23521..e72af899b36a2643fd08ab2567cb06e7b610ac45 100644 (file)
--- a/doc/man3/SSL_accept_stream.pod
+++ b/doc/man3/SSL_accept_stream.pod
@@ -31,7 +31,7 @@ SSL object; for more information, see 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,
+passing the flag B<SSL_ACCEPT_STREAM_NO_BLOCK> in I<flags>. If this flag is set,
 this function never blocks.
 
 SSL_get_accept_stream_queue_len() returns the number of incoming streams
@@ -59,6 +59,7 @@ man(7) pages are merged
 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,
 or if called on a SSL object other than a QUIC connection SSL object.
+L<SSL_get_error(3)> can be used to obtain further information in this case.
 
 SSL_get_accept_stream_queue_len() returns the number of incoming streams
 currently waiting in the accept queue, or 0 if called on a SSL object other than

diff --git a/doc/man3/SSL_attach_stream.pod b/doc/man3/SSL_attach_stream.pod
index 8f837acc6eb28fce1f5e4045432ac48bf181d367..298000ac2e44f351d0f0ca0690a838e0bdcf1dc7 100644 (file)
--- a/doc/man3/SSL_attach_stream.pod
+++ b/doc/man3/SSL_attach_stream.pod
@@ -87,7 +87,7 @@ SSL_set_default_stream_mode() can be used to configure or disable default stream
 handling. It can only be called on a QUIC connection SSL object prior to any
 default stream being created. If used, it is recommended to call it immediately
 after calling L<SSL_new(3)>, prior to initiating a connection. The argument
-B<mode> may be one of the following options:
+I<mode> may be one of the following options:
 
 =over 4
 

diff --git a/doc/man3/SSL_get_conn_close_info.pod b/doc/man3/SSL_get_conn_close_info.pod
index 5f9a2c3e382e0294f83f4d550b17fb7e12a37843..9fbf6fe9bcedad0a4d499d4701b041a65a116cc7 100644 (file)
--- a/doc/man3/SSL_get_conn_close_info.pod
+++ b/doc/man3/SSL_get_conn_close_info.pod
@@ -24,41 +24,41 @@ SSL_get_conn_close_info - get information about why a QUIC connection was closed
 The SSL_get_conn_close_info() function provides information about why and how a
 QUIC connection was closed.
 
-Connection closure information is written to B<*info>, which must be non-NULL.
-B<info_len> must be set to B<sizeof(*info)>.
+Connection closure information is written to I<*info>, which must be non-NULL.
+I<info_len> must be set to C<sizeof(*info)>.
 
 The following fields are set:
 
 =over 4
 
-=item B<error_code>
+=item I<error_code>
 
 This is a 62-bit QUIC error code. It is either a 62-bit application error code
-(if B<is_transport> is 0) or a  62-bit standard QUIC transport error code (if
-B<is_transport> is 1).
+(if I<is_transport> is 0) or a  62-bit standard QUIC transport error code (if
+I<is_transport> is 1).
 
-=item B<reason>
+=item I<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 B<reason_len>. While, if non-NULL, OpenSSL guarantees that this string
+given in I<reason_len>. 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 B<reason_len> is recommended.
+of I<reason_len> is recommended.
 
 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.
 
-=item B<is_local>
+=item I<is_local>
 
 If 1, connection closure was locally triggered. This could be due to an
-application request (e.g. if B<is_transport> is 0), or (if B<is_transport> is 1)
+application request (e.g. if I<is_transport> is 0), or (if I<is_transport> is 1)
 due to logic internal to the QUIC implementation (for example, if the peer
 engages in a protocol violation, or an idle timeout occurs).
 
 If 0, connection closure was remotely triggered.
 
-=item B<is_transport>
+=item I<is_transport>
 
 If 1, connection closure was triggered for QUIC protocol reasons.
 

diff --git a/doc/man3/SSL_get_stream_read_state.pod b/doc/man3/SSL_get_stream_read_state.pod
index d04a1ef88a3ddbd8096880f0122cd1f327e83eb0..7373e1dbff01c3b58c287a50cae0e343a434d10a 100644 (file)
--- a/doc/man3/SSL_get_stream_read_state.pod
+++ b/doc/man3/SSL_get_stream_read_state.pod
@@ -36,24 +36,24 @@ They both return one of the following values:
 
 =over 4
 
-=item SSL_STREAM_STATE_NONE
+=item B<SSL_STREAM_STATE_NONE>
 
 This value is returned if called on a non-QUIC SSL object, or on a QUIC
 connection SSL object without a default stream attached.
 
-=item SSL_STREAM_STATE_OK
+=item B<SSL_STREAM_STATE_OK>
 
 This value is returned on a stream which has not been concluded and remains
 healthy.
 
-=item SSL_STREAM_STATE_WRONG_DIR
+=item B<SSL_STREAM_STATE_WRONG_DIR>
 
 This value is returned 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.
 
-=item SSL_STREAM_STATE_FINISHED
+=item B<SSL_STREAM_STATE_FINISHED>
 
 For SSL_get_stream_read_state(), this value is returned when the remote peer has
 signalled the end of the receiving part of the stream. Note that there may still
@@ -64,7 +64,7 @@ For SSL_get_stream_write_state(), this value is returned when the local
 application has concluded the stream using L<SSL_stream_conclude(3)>. Future
 L<SSL_write(3)> calls will not succeed.
 
-=item SSL_STREAM_STATE_RESET_LOCAL
+=item B<SSL_STREAM_STATE_RESET_LOCAL>
 
 This value is returned when the applicable stream part was reset by the local
 application.
@@ -83,7 +83,7 @@ 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.
 
-=item SSL_STREAM_STATE_RESET_REMOTE
+=item B<SSL_STREAM_STATE_RESET_REMOTE>
 
 This value is returned when the applicable stream part was reset by the remote
 peer.
@@ -101,7 +101,7 @@ 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.
 
-=item SSL_STREAM_STATE_CONN_CLOSED
+=item B<SSL_STREAM_STATE_CONN_CLOSED>
 
 The QUIC connection to which the stream belongs was closed. You can obtain
 information about the circumstances of this closure using
@@ -115,7 +115,7 @@ SSL_get_stream_write_state() will also return this state.
 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 B<*app_error_code>.
+application error code is written to I<*app_error_code>.
 
 =head1 NOTES
 

diff --git a/doc/man3/SSL_set_incoming_stream_reject_policy.pod b/doc/man3/SSL_set_incoming_stream_reject_policy.pod
index 3e859b26adc8086b1d513839ce08a3a27e714fd5..dfc3dffb03a61c47340ed583e23b46ca3bf9d023 100644 (file)
--- a/doc/man3/SSL_set_incoming_stream_reject_policy.pod
+++ b/doc/man3/SSL_set_incoming_stream_reject_policy.pod
@@ -28,11 +28,11 @@ operation with a default stream on a QUIC connection SSL object are not passed
 remotely-initiated streams by a peer which those applications are not prepared
 to handle.
 
-B<app_error_code> is an application error code which will be used in any QUIC
+I<app_error_code> is an application error code which will be used in any QUIC
 B<STOP_SENDING> or B<RESET_STREAM> frames generated to implement the rejection
 policy. The default application error code is 0.
 
-The valid values for B<policy> are:
+The valid values for I<policy> are:
 
 =over 4
 

diff --git a/doc/man3/SSL_stream_reset.pod b/doc/man3/SSL_stream_reset.pod
index 3f9159024a17e6609abdef9d23058d030d116b4e..e2f6fd35bc76752d737a425b1fcc2e969fea469b 100644 (file)
--- a/doc/man3/SSL_stream_reset.pod
+++ b/doc/man3/SSL_stream_reset.pod
@@ -22,10 +22,10 @@ The SSL_stream_reset() function resets the send part of a QUIC stream when
 called on a QUIC stream SSL object, or on a QUIC connection SSL object with  a
 default stream attached.
 
-If B<args> is non-NULL, B<args_len> must be set to B<sizeof(*args)>.
+If I<args> is non-NULL, I<args_len> must be set to C<sizeof(*args)>.
 
-B<quic_error_code> is an application-specified error code, which must be in the
-range [0, 2**62-1]. If B<args> is NULL, a value of 0 is used.
+I<quic_error_code> is an application-specified error code, which must be in the
+range [0, 2**62-1]. If I<args> is NULL, a value of 0 is used.
 
 Resetting a stream indicates to an application that the sending part of the
 stream is terminating abnormally. When a stream is reset, the implementation

diff --git a/include/internal/quic_stream_map.h b/include/internal/quic_stream_map.h
index 920f3144b46fb08e4c1927ad9eb1c08289e9ac31..1af0c57d1eec01686168ccd17ab68d3de525d227 100644 (file)
--- a/include/internal/quic_stream_map.h
+++ b/include/internal/quic_stream_map.h
@@ -69,7 +69,7 @@ struct quic_stream_st {
 
     /*
      * Application Error Code (AEC) for incoming RESET_STREAM frame.
-     * This  is only valid if peer_reset_stream is 1.
+     * This is only valid if peer_reset_stream is 1.
      */
     uint64_t        peer_reset_stream_aec;