Add the missing RETURN VALUES section and reorder the content

accordingly.  Make some statements more precise, and point out
some dangerous traps in these ill-designed interfaces.
Also do some minor polishing while here.

Triggered by OpenSSL commit 1f13ad31 Dec 25 17:50:39 2017 +0800
by Paul Yang, but not using most of his wording because that is in
part redundant, in part incomplete, and in part outright wrong.

diff --git a/lib/libcrypto/man/ASN1_STRING_length.3 b/lib/libcrypto/man/ASN1_STRING_length.3
index 2c79748..398d49e 100644 (file)
--- a/lib/libcrypto/man/ASN1_STRING_length.3
+++ b/lib/libcrypto/man/ASN1_STRING_length.3
@@ -1,8 +1,26 @@
-.\"    $OpenBSD: ASN1_STRING_length.3,v 1.6 2016/12/25 22:15:10 schwarze Exp $
-.\"    OpenSSL 99d63d46 Tue Jun 21 07:03:34 2016 -0400
+.\" $OpenBSD: ASN1_STRING_length.3,v 1.7 2018/02/12 15:45:12 schwarze Exp $
+.\" full merge up to: OpenSSL 99d63d46 Tue Jun 21 07:03:34 2016 -0400
+.\" selective merge up to: OpenSSL 61f805c1 Jan 16 01:01:46 2018 +0800
 .\"
-.\" This file was written by Dr. Stephen Henson.
-.\" Copyright (c) 2002, 2006, 2013, 2015, 2016 The OpenSSL Project.
+.\" This file is a derived work.
+.\" The changes are covered by the following Copyright and license:
+.\"
+.\" Copyright (c) 2018 Ingo Schwarze <schwarze@openbsd.org>
+.\"
+.\" 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) 2002, 2006, 2013, 2015, 2016, 2017 The OpenSSL Project.
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -49,7 +67,7 @@
 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
 .\"
-.Dd $Mdocdate: December 25 2016 $
+.Dd $Mdocdate: February 12 2018 $
 .Dt ASN1_STRING_LENGTH 3
 .Os
 .Sh NAME
@@ -107,27 +125,24 @@ These functions manipulate
 structures.
 .Pp
 .Fn ASN1_STRING_cmp
-compares
+compares the type, the length, and the content of
 .Fa a
 and
-.Fa b
-and returns 0 if the two are identical.
-The string types and the content are compared.
+.Fa b .
 .Pp
 .Fn ASN1_STRING_data
 returns an internal pointer to the data of
 .Fa x .
-Since this is an internal pointer, it should
-.Em not
-be freed or modified in any way.
+It should not be freed or modified in any way.
 .Pp
 .Fn ASN1_STRING_dup
-returns a copy of the structure
+copies
 .Fa a .
 .Pp
 .Fn ASN1_STRING_length
-returns the length of the content of
-.Fa x .
+returns the length attribute of
+.Fa x ,
+measured in bytes.
 .Pp
 .Fn ASN1_STRING_length_set
 sets the length attribute of
@@ -139,39 +154,46 @@ It may put
 into an inconsistent internal state.
 .Pp
 .Fn ASN1_STRING_set
-sets the data of the string
+sets the length attribute of
 .Fa str
-to the buffer
+to
+.Fa len
+and copies that number of bytes from
 .Fa data
-of length
+into
+.Fa str .
+If
+.Fa len
+is -1, then
+.Fn strlen data
+is used instead of
 .Fa len .
-The supplied data is copied.
 If
+.Fa data
+is
+.Dv NULL ,
+the content of
+.Fa str
+remains uninitialized; that is not considered an error unless
 .Fa len
-is -1 then the length is determined by
-.Fn strlen data .
+is negative.
 .Pp
 .Fn ASN1_STRING_to_UTF8
 converts the string
 .Fa in
-to UTF8 format.
+to UTF-8 format.
 The converted data is copied into a newly allocated buffer
-.Fa out .
-The length of
-.Fa out
-is returned or a negative error code.
+.Pf * Fa out .
 The buffer
-.Fa out
+.Pf * Fa out
 should be freed using
 .Xr free 3 .
 .Pp
 .Fn ASN1_STRING_type
 returns the type of
-.Fa x ,
-using standard constants such as
-.Dv V_ASN1_OCTET_STRING .
+.Fa x .
 .Pp
-Almost all ASN.1 types in OpenSSL are represented as
+Almost all ASN.1 types are represented as
 .Vt ASN1_STRING
 structures.
 Other types such as
@@ -200,17 +222,53 @@ be used instead.
 In general it cannot be assumed that the data returned by
 .Fn ASN1_STRING_data
 is NUL terminated, and it may contain embedded NUL characters.
-The actual format of the data will depend on the actual string type itself:
+The format of the data depends on the string type:
 for example for an
 .Vt IA5String
-the data will be ASCII, for a
+the data contains ASCII characters, a
 .Vt BMPString
 two bytes per character in big endian format, and a
 .Vt UTF8String
-will be in UTF8 format.
+UTF-8 characters.
 .Pp
-Similar care should be take to ensure the data is in the correct format
+Similar care should be taken to ensure the data is in the correct format
 when calling
 .Fn ASN1_STRING_set .
+.Sh RETURN VALUES
+.Fn ASN1_STRING_cmp
+returns 0 if the type, the length, and the content of
+.Fa a
+and
+.Fa b
+agree, or a non-zero value otherwise.
+In contrast to
+.Xr strcmp 3 ,
+the sign of the return value does not indicate lexicographical ordering.
+.Pp
+.Fn ASN1_STRING_data
+returns an internal pointer to the data of
+.Fa x .
+.Pp
+.Fn ASN1_STRING_dup
+returns a pointer to a newly allocated
+.Vt ASN1_STRING
+structure or
+.Dv NULL
+if an error occurred.
+.Pp
+.Fn ASN1_STRING_length
+returns a number of bytes.
+.Pp
+.Fn ASN1_STRING_set
+returns 1 on success or 0 on failure.
+.Pp
+.Fn ASN1_STRING_to_UTF8
+returns the number of bytes in the output buffer
+.Pf * Fa out ,
+or a negative number if an error occurred.
+.Pp
+.Fn ASN1_STRING_type
+returns an integer constant, for example
+.Dv V_ASN1_OCTET_STRING .
 .Sh SEE ALSO
 .Xr ERR_get_error 3