From: schwarze Date: Sun, 30 Apr 2023 14:03:47 +0000 (+0000) Subject: Make the descriptions of BIO_get_retry_BIO(3) and BIO_get_retry_reason(3) X-Git-Url: http://artulab.com/gitweb/?a=commitdiff_plain;h=1a959a837d0843a57a982ff3e30307f767263ffb;p=openbsd Make the descriptions of BIO_get_retry_BIO(3) and BIO_get_retry_reason(3) more precise. Among other improvements, describe the three BIO_RR_* constants serving as reason codes. --- diff --git a/lib/libcrypto/man/BIO_should_retry.3 b/lib/libcrypto/man/BIO_should_retry.3 index 4d7a214db64..9b93743516c 100644 --- a/lib/libcrypto/man/BIO_should_retry.3 +++ b/lib/libcrypto/man/BIO_should_retry.3 @@ -1,8 +1,25 @@ -.\" $OpenBSD: BIO_should_retry.3,v 1.10 2022/11/27 19:11:11 schwarze Exp $ +.\" $OpenBSD: BIO_should_retry.3,v 1.11 2023/04/30 14:03:47 schwarze Exp $ .\" full merge up to: OpenSSL 99d63d46 Oct 26 13:56:48 2016 -0400 .\" selective merge up to: OpenSSL 57fd5170 May 13 11:24:11 2018 +0200 .\" -.\" This file was written by Dr. Stephen Henson . +.\" This file is a derived work. +.\" The changes are covered by the following Copyright and license: +.\" +.\" Copyright (c) 2023 Ingo Schwarze +.\" +.\" Permission to use, copy, modify, and distribute this software for any +.\" purpose with or without fee is hereby granted, provided that the above +.\" copyright notice and this permission notice appear in all copies. +.\" +.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES +.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF +.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR +.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES +.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN +.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF +.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE. +.\" +.\" The original file was written by Dr. Stephen Henson . .\" Copyright (c) 2000, 2010, 2016 The OpenSSL Project. All rights reserved. .\" .\" Redistribution and use in source and binary forms, with or without @@ -49,7 +66,7 @@ .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED .\" OF THE POSSIBILITY OF SUCH DAMAGE. .\" -.Dd $Mdocdate: November 27 2022 $ +.Dd $Mdocdate: April 30 2023 $ .Dt BIO_SHOULD_RETRY 3 .Os .Sh NAME @@ -140,18 +157,50 @@ Current BIO types only set one of the flags at a time. .Pp .Fn BIO_get_retry_BIO determines the precise reason for the special condition. -It returns the BIO that caused this condition and if +It walks the BIO chain starting at +.Fa bio +and returns the BIO that caused this condition. +If there is no special condition, +.Fa bio +itself is returned. +If .Fa reason -is not +is not a .Dv NULL -it contains the reason code. -The meaning of the reason code and the action that should be taken -depends on the type of BIO that resulted in this condition. +pointer, +.Pf * Fa reason +is set to one of the following reason codes: +.Bl -tag -width 1n -offset 3n +.It 0 +There is no special condition. +.It Dv BIO_RR_ACCEPT +.Xr accept 2 +would have blocked. +This can occur for BIOs created from +.Xr BIO_s_accept 3 +or +.Xr BIO_f_ssl 3 . +.It Dv BIO_RR_CONNECT +.Xr connect 2 +would have blocked. +This can occur for BIOs created from +.Xr BIO_s_connect 3 +or +.Xr BIO_f_ssl 3 . +.It Dv BIO_RR_SSL_X509_LOOKUP +An application callback set by +.Xr SSL_CTX_set_client_cert_cb 3 +has asked to be called again. +This can occur for BIOs created from +.Xr BIO_f_ssl 3 . +.El .Pp .Fn BIO_get_retry_reason -returns the reason for a special condition -if passed the relevant BIO, for example as returned by -.Fn BIO_get_retry_BIO . +returns one of the above reason codes for a special condition that occurred in +.Fa bio . +It does not walk the chain and returns 0 if no special condition occurred in +.Fa bio +itself. .Pp .Fn BIO_set_retry_reason sets the retry reason for a special condition for the given