summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/man/ASN1_OBJECT_new.3
diff options
context:
space:
mode:
authorschwarze <>2017-01-04 05:14:51 +0000
committerschwarze <>2017-01-04 05:14:51 +0000
commita98a132e1b5f37c52906129d09c4a9853321a1c4 (patch)
tree8e331ada8bb4ae35121a26f3453e9f02e803b3ff /src/lib/libcrypto/man/ASN1_OBJECT_new.3
parent38354d6effee546e2cc9f9a651d007c0611a0ae0 (diff)
downloadopenbsd-a98a132e1b5f37c52906129d09c4a9853321a1c4.tar.gz
openbsd-a98a132e1b5f37c52906129d09c4a9853321a1c4.tar.bz2
openbsd-a98a132e1b5f37c52906129d09c4a9853321a1c4.zip
Describe what ASN1_OBJECT_new(3), ASN1_OBJECT_free(3), OBJ_dup(3),
and OBJ_create(3) really do rather than making broad and incomplete statements that are only true in some cases. Improve the one-line descriptions. Some minor wording improvements while here. There is obviously more work to do in the vicinity...
Diffstat (limited to 'src/lib/libcrypto/man/ASN1_OBJECT_new.3')
-rw-r--r--src/lib/libcrypto/man/ASN1_OBJECT_new.377
1 files changed, 52 insertions, 25 deletions
diff --git a/src/lib/libcrypto/man/ASN1_OBJECT_new.3 b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
index 55a90bbcb2..e7c3540b3a 100644
--- a/src/lib/libcrypto/man/ASN1_OBJECT_new.3
+++ b/src/lib/libcrypto/man/ASN1_OBJECT_new.3
@@ -1,7 +1,24 @@
1.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.7 2016/11/10 14:34:18 jmc Exp $ 1.\" $OpenBSD: ASN1_OBJECT_new.3,v 1.8 2017/01/04 05:14:51 schwarze Exp $
2.\" OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400 2.\" OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
3.\" 3.\"
4.\" This file was written by Dr. Stephen Henson. 4.\" This file is a derived work.
5.\" The changes are covered by the following Copyright and license:
6.\"
7.\" Copyright (c) 2017 Ingo Schwarze <schwarze@openbsd.org>
8.\"
9.\" Permission to use, copy, modify, and distribute this software for any
10.\" purpose with or without fee is hereby granted, provided that the above
11.\" copyright notice and this permission notice appear in all copies.
12.\"
13.\" THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
14.\" WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
15.\" MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
16.\" ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
17.\" WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
18.\" ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
19.\" OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
20.\"
21.\" The original file was written by Dr. Stephen Henson.
5.\" Copyright (c) 2002, 2006 The OpenSSL Project. All rights reserved. 22.\" Copyright (c) 2002, 2006 The OpenSSL Project. All rights reserved.
6.\" 23.\"
7.\" Redistribution and use in source and binary forms, with or without 24.\" Redistribution and use in source and binary forms, with or without
@@ -48,13 +65,13 @@
48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 65.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 66.\" OF THE POSSIBILITY OF SUCH DAMAGE.
50.\" 67.\"
51.Dd $Mdocdate: November 10 2016 $ 68.Dd $Mdocdate: January 4 2017 $
52.Dt ASN1_OBJECT_NEW 3 69.Dt ASN1_OBJECT_NEW 3
53.Os 70.Os
54.Sh NAME 71.Sh NAME
55.Nm ASN1_OBJECT_new , 72.Nm ASN1_OBJECT_new ,
56.Nm ASN1_OBJECT_free 73.Nm ASN1_OBJECT_free
57.Nd ASN.1 object allocation functions 74.Nd ASN.1 object identifiers
58.Sh SYNOPSIS 75.Sh SYNOPSIS
59.In openssl/asn1.h 76.In openssl/asn1.h
60.Ft ASN1_OBJECT * 77.Ft ASN1_OBJECT *
@@ -66,34 +83,45 @@
66.Fa "ASN1_OBJECT *a" 83.Fa "ASN1_OBJECT *a"
67.Fc 84.Fc
68.Sh DESCRIPTION 85.Sh DESCRIPTION
69The ASN1_OBJECT allocation routines allocate and free an 86.Fn ASN1_OBJECT_new
87allocates and initializes an empty
70.Vt ASN1_OBJECT 88.Vt ASN1_OBJECT
71structure, which represents an ASN.1 OBJECT IDENTIFIER. 89object, representing an ASN.1 OBJECT IDENTIFIER.
90It can hold a short name, a long name, a numeric identifier (NID),
91and a sequence of integers identifying a node in the International
92Object Identifier tree as specified in ITU-T recommendation X.660.
93The new object is marked as dynamically allocated.
72.Pp 94.Pp
95Application programs normally use utility functions like
96.Xr OBJ_nid2obj 3
97rather than using
73.Fn ASN1_OBJECT_new 98.Fn ASN1_OBJECT_new
74allocates and initializes an 99directly.
75.Vt ASN1_OBJECT
76structure.
77.Pp 100.Pp
78.Fn ASN1_OBJECT_free 101.Fn ASN1_OBJECT_free
79frees up the 102has the following effects:
80.Vt ASN1_OBJECT 103.Pp
81structure 104All data contained in
82.Fa a . 105.Fa a
106that is marked as dynamically allocated is freed,
107and the respective fields of
108.Fa a
109become empty.
110Contained data not marked as dynamically allocated remains intact.
111.Pp
112If the object
113.Fa a
114itself is marked as dynamically allocated, it is freed.
115Otherwise, the pointer
116.Fa a
117remains valid.
118.Pp
83If 119If
84.Fa a 120.Fa a
85is a 121is a
86.Dv NULL 122.Dv NULL
87pointer, no action occurs. 123pointer or if neither the object itself nor any of its content
88.Pp 124is marked as dynamically allocated, no action occurs.
89Although
90.Fn ASN1_OBJECT_new
91allocates a new
92.Vt ASN1_OBJECT
93structure, it is almost never used in applications.
94The ASN.1 object utility functions such as
95.Xr OBJ_nid2obj 3
96are used instead.
97.Sh RETURN VALUES 125.Sh RETURN VALUES
98If the allocation fails, 126If the allocation fails,
99.Fn ASN1_OBJECT_new 127.Fn ASN1_OBJECT_new
@@ -101,10 +129,9 @@ returns
101.Dv NULL 129.Dv NULL
102and sets an error code that can be obtained by 130and sets an error code that can be obtained by
103.Xr ERR_get_error 3 . 131.Xr ERR_get_error 3 .
104Otherwise it returns a pointer to the newly allocated structure. 132Otherwise it returns a pointer to the new object.
105.Sh SEE ALSO 133.Sh SEE ALSO
106.Xr d2i_ASN1_OBJECT 3 , 134.Xr d2i_ASN1_OBJECT 3 ,
107.Xr ERR_get_error 3 ,
108.Xr OBJ_nid2obj 3 135.Xr OBJ_nid2obj 3
109.Sh HISTORY 136.Sh HISTORY
110.Fn ASN1_OBJECT_new 137.Fn ASN1_OBJECT_new