1 files changed, 103 insertions, 0 deletions
diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3
new file mode 100644
index 0000000000..0444bbe15a
--- /dev/null
+++ b/src/lib/libcrypto/man/ASN1_item_new.3
@@ -0,0 +1,103 @@
+.\"     $OpenBSD: ASN1_item_new.3,v 1.1 2016/12/24 21:42:29 schwarze Exp $
+.\"
+.\" Copyright (c) 2016 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.
+.\"
+.Dd $Mdocdate: December 24 2016 $
+.Dt ASN1_ITEM_NEW 3
+.Os
+.Sh NAME
+.Nm ASN1_item_new ,
+.Nm ASN1_item_free
+.Nd generic ASN.1 value constructor and destructor
+.Sh SYNOPSIS
+.In openssl/asn1.h
+.Ft ASN1_VALUE *
+.Fo ASN1_item_new
+.Fa "const ASN1_ITEM *it"
+.Fc
+.Ft void
+.Fo ASN1_item_free
+.Fa "ASN1_VALUE *val_in"
+.Fa "const ASN1_ITEM *it"
+.Fc
+.Sh DESCRIPTION
+.Fn ASN1_item_new
+allocates and initializes an empty ASN.1 value
+of the type described by the global static object
+.Fa it .
+.Pp
+.Fn ASN1_item_free
+frees an ASN.1 value of the type described by
+.Fa it .
+If the true type of
+.Fa val_in
+fails to match the specified
+.Fa it ,
+buffer overflows and segmentation faults are likely to occur.
+It is not possible to recover the type of an
+.Vt ASN1_VALUE
+object by inspecting it; the type always needs to be remembered
+separately.
+.Pp
+.Vt ASN1_VALUE
+is an incomplete type, and pointers to it always require casting
+to the correct complete type before they can be dereferenced.
+For all practical purposes, a pointer to
+.Vt ASN1_VALUE
+is equivalent to a
+.Vt void
+pointer.
+.Pp
+Depending on
+.Fa it ,
+there are more than 150 different types that
+.Fn ASN1_item_new
+may return.
+Most of them are pointers to structures or pointers to arrays of
+structures, but there are a few exceptions, for example:
+If
+.Fa it
+is
+.Dv ASN1_NULL_it ,
+.Fn ASN1_item_new
+returns a specific invalid pointer representing the unique
+.Vt ASN1_NULL
+object.
+If
+.Fa it
+is
+.Dv ASN1_BOOLEAN_it
+or
+.Dv LONG_it ,
+.Fn ASN1_item_new
+does not return a pointer at all, but a
+.Vt long
+value cast to
+.Vt ASN1_VALUE * .
+.Sh RETURN VALUES
+.Fn ASN1_item_new
+returns the new
+.Vt ASN1_VALUE
+object or
+.Dv NULL
+if an error occurs.
+.Sh SEE ALSO
+.Xr ASN1_item_d2i 3 ,
+.Xr OBJ_nid2obj 3
+.Sh BUGS
+The
+.Vt ASN1_VALUE
+type compromises type safety and invites programming mistakes that
+will typically have severe consequences.

diff --git a/src/lib/libcrypto/man/ASN1_item_new.3 b/src/lib/libcrypto/man/ASN1_item_new.3 new file mode 100644 index 0000000000..0444bbe15a --- /dev/null +++ b/src/lib/libcrypto/man/ASN1_item_new.3
@@ -0,0 +1,103 @@
	1	.\" $OpenBSD: ASN1_item_new.3,v 1.1 2016/12/24 21:42:29 schwarze Exp $
	2	.\"
	3	.\" Copyright (c) 2016 Ingo Schwarze <schwarze@openbsd.org>
	4	.\"
	5	.\" Permission to use, copy, modify, and distribute this software for any
	6	.\" purpose with or without fee is hereby granted, provided that the above
	7	.\" copyright notice and this permission notice appear in all copies.
	8	.\"
	9	.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
	10	.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
	11	.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
	12	.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
	13	.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
	14	.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
	15	.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
	16	.\"
	17	.Dd $Mdocdate: December 24 2016 $
	18	.Dt ASN1_ITEM_NEW 3
	19	.Os
	20	.Sh NAME
	21	.Nm ASN1_item_new ,
	22	.Nm ASN1_item_free
	23	.Nd generic ASN.1 value constructor and destructor
	24	.Sh SYNOPSIS
	25	.In openssl/asn1.h
	26	.Ft ASN1_VALUE *
	27	.Fo ASN1_item_new
	28	.Fa "const ASN1_ITEM *it"
	29	.Fc
	30	.Ft void
	31	.Fo ASN1_item_free
	32	.Fa "ASN1_VALUE *val_in"
	33	.Fa "const ASN1_ITEM *it"
	34	.Fc
	35	.Sh DESCRIPTION
	36	.Fn ASN1_item_new
	37	allocates and initializes an empty ASN.1 value
	38	of the type described by the global static object
	39	.Fa it .
	40	.Pp
	41	.Fn ASN1_item_free
	42	frees an ASN.1 value of the type described by
	43	.Fa it .
	44	If the true type of
	45	.Fa val_in
	46	fails to match the specified
	47	.Fa it ,
	48	buffer overflows and segmentation faults are likely to occur.
	49	It is not possible to recover the type of an
	50	.Vt ASN1_VALUE
	51	object by inspecting it; the type always needs to be remembered
	52	separately.
	53	.Pp
	54	.Vt ASN1_VALUE
	55	is an incomplete type, and pointers to it always require casting
	56	to the correct complete type before they can be dereferenced.
	57	For all practical purposes, a pointer to
	58	.Vt ASN1_VALUE
	59	is equivalent to a
	60	.Vt void
	61	pointer.
	62	.Pp
	63	Depending on
	64	.Fa it ,
	65	there are more than 150 different types that
	66	.Fn ASN1_item_new
	67	may return.
	68	Most of them are pointers to structures or pointers to arrays of
	69	structures, but there are a few exceptions, for example:
	70	If
	71	.Fa it
	72	is
	73	.Dv ASN1_NULL_it ,
	74	.Fn ASN1_item_new
	75	returns a specific invalid pointer representing the unique
	76	.Vt ASN1_NULL
	77	object.
	78	If
	79	.Fa it
	80	is
	81	.Dv ASN1_BOOLEAN_it
	82	or
	83	.Dv LONG_it ,
	84	.Fn ASN1_item_new
	85	does not return a pointer at all, but a
	86	.Vt long
	87	value cast to
	88	.Vt ASN1_VALUE * .
	89	.Sh RETURN VALUES
	90	.Fn ASN1_item_new
	91	returns the new
	92	.Vt ASN1_VALUE
	93	object or
	94	.Dv NULL
	95	if an error occurs.
	96	.Sh SEE ALSO
	97	.Xr ASN1_item_d2i 3 ,
	98	.Xr OBJ_nid2obj 3
	99	.Sh BUGS
	100	The
	101	.Vt ASN1_VALUE
	102	type compromises type safety and invites programming mistakes that
	103	will typically have severe consequences.