Move the explanations related to *ptree closer together and correct

the lie that *ptree is set upon success - in some cases of success,
it is set to NULL, whereas in some cases of failure, a non-trivial
tree may be returned.

beck@ pointed out that statements related to *ptree were scattered
all over the place, and this patch works for him.

1 files changed, 19 insertions, 16 deletions

diff --git a/lib/libcrypto/man/X509_policy_check.3 b/lib/libcrypto/man/X509_policy_check.3
index 445f22ddeab..e4b3be0d437 100644
--- a/lib/libcrypto/man/X509_policy_check.3
+++ b/lib/libcrypto/man/X509_policy_check.3
@@ -1,4 +1,4 @@
-.\" $OpenBSD: X509_policy_check.3,v 1.4 2021/07/29 12:39:47 schwarze Exp $
+.\" $OpenBSD: X509_policy_check.3,v 1.5 2021/07/30 15:01:40 schwarze Exp $
 .\"
 .\" Copyright (c) 2021 Ingo Schwarze <schwarze@openbsd.org>
 .\"
@@ -14,7 +14,7 @@
 .\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
 .\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
 .\"
-.Dd $Mdocdate: July 29 2021 $
+.Dd $Mdocdate: July 30 2021 $
 .Dt X509_POLICY_CHECK 3
 .Os
 .Sh NAME
@@ -44,9 +44,6 @@ The
 input argument contains the prospective certification path
 according to RFC 5280 paragraph 6.1.1(a), starting with the
 target certificate and ending with the trust anchor.
-If a policy tree is returned, the reference count of each of the
-.Fa certs
-is incremented by 1.
 .Pp
 The
 .Fa policy_oids
@@ -79,7 +76,14 @@ as defined by RFC 5280 paragraph 6.1.1(e).
 It disables policy mapping in the certification path.
 .El
 .Pp
-Upon success, a pointer to the
+Upon success and in some cases of failure, the storage location pointed to by
+.Fa pexplicit_policy
+is set to 1 if
+.Dv X509_V_FLAG_EXPLICIT_POLICY
+was requested.
+Otherwise, it is set to 0.
+.Pp
+In many cases of success and in a few cases of failure, a pointer to the
 .Vt valid_policy_tree
 output value mentioned in RFC 5280 section 6.1.6 is returned in
 .Pf * Fa ptree .
@@ -94,23 +98,22 @@ of
 and an empty
 .Fa qualifier_set .
 .Pp
-Upon success and in some cases of failure, the storage location pointed to by
-.Fa pexplicit_policy
-is set to 1 if
-.Dv X509_V_FLAG_EXPLICIT_POLICY
-was requested.
-Otherwise, it is set to 0.
-.Pp
+If a policy tree is returned, the reference count of each of the
+.Fa certs
+is incremented by 1.
+In that case, the caller is responsible for calling
 .Fn X509_policy_tree_free
-releases all memory used by the
+to release all memory used by the
 .Fa tree
-and decrements the reference counts
+and to decrement the reference counts
 of the certificates referenced from it by 1.
 If
 .Fa tree
 is a
 .Dv NULL
-pointer, no action occurs.
+pointer,
+.Fn X509_policy_tree_free
+has no effect.
 .Sh RETURN VALUES
 .Fn X509_policy_check
 returns these values: