lib/libcrypto/man/ASN1_OBJECT_new.3

   1 .\"     $OpenBSD: ASN1_OBJECT_new.3,v 1.9 2018/03/20 18:35:13 schwarze Exp $
   2 .\"     OpenSSL 99d63d4 Mar 19 12:28:58 2016 -0400
   3 .\"
   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.
  22 .\" Copyright (c) 2002, 2006 The OpenSSL Project.  All rights reserved.
  23 .\"
  24 .\" Redistribution and use in source and binary forms, with or without
  25 .\" modification, are permitted provided that the following conditions
  26 .\" are met:
  27 .\"
  28 .\" 1. Redistributions of source code must retain the above copyright
  29 .\"    notice, this list of conditions and the following disclaimer.
  30 .\"
  31 .\" 2. Redistributions in binary form must reproduce the above copyright
  32 .\"    notice, this list of conditions and the following disclaimer in
  33 .\"    the documentation and/or other materials provided with the
  34 .\"    distribution.
  35 .\"
  36 .\" 3. All advertising materials mentioning features or use of this
  37 .\"    software must display the following acknowledgment:
  38 .\"    "This product includes software developed by the OpenSSL Project
  39 .\"    for use in the OpenSSL Toolkit. (http://www.openssl.org/)"
  40 .\"
  41 .\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to
  42 .\"    endorse or promote products derived from this software without
  43 .\"    prior written permission. For written permission, please contact
  44 .\"    openssl-core@openssl.org.
  45 .\"
  46 .\" 5. Products derived from this software may not be called "OpenSSL"
  47 .\"    nor may "OpenSSL" appear in their names without prior written
  48 .\"    permission of the OpenSSL Project.
  49 .\"
  50 .\" 6. Redistributions of any form whatsoever must retain the following
  51 .\"    acknowledgment:
  52 .\"    "This product includes software developed by the OpenSSL Project
  53 .\"    for use in the OpenSSL Toolkit (http://www.openssl.org/)"
  54 .\"
  55 .\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY
  56 .\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
  57 .\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
  58 .\" PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE OpenSSL PROJECT OR
  59 .\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
  60 .\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
  61 .\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
  62 .\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
  63 .\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
  64 .\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
  65 .\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
  66 .\" OF THE POSSIBILITY OF SUCH DAMAGE.
  67 .\"
  68 .Dd $Mdocdate: March 20 2018 $
  69 .Dt ASN1_OBJECT_NEW 3
  70 .Os
  71 .Sh NAME
  72 .Nm ASN1_OBJECT_new ,
  73 .Nm ASN1_OBJECT_free
  74 .Nd ASN.1 object identifiers
  75 .Sh SYNOPSIS
  76 .In openssl/asn1.h
  77 .Ft ASN1_OBJECT *
  78 .Fo ASN1_OBJECT_new
  79 .Fa void
  80 .Fc
  81 .Ft void
  82 .Fo ASN1_OBJECT_free
  83 .Fa "ASN1_OBJECT *a"
  84 .Fc
  85 .Sh DESCRIPTION
  86 .Fn ASN1_OBJECT_new
  87 allocates and initializes an empty
  88 .Vt ASN1_OBJECT
  89 object, representing an ASN.1 OBJECT IDENTIFIER.
  90 It can hold a short name, a long name, a numeric identifier (NID),
  91 and a sequence of integers identifying a node in the International
  92 Object Identifier tree as specified in ITU-T recommendation X.660.
  93 The new object is marked as dynamically allocated.
  94 .Pp
  95 Application programs normally use utility functions like
  96 .Xr OBJ_nid2obj 3
  97 rather than using
  98 .Fn ASN1_OBJECT_new
  99 directly.
 100 .Pp
 101 .Fn ASN1_OBJECT_free
 102 has the following effects:
 103 .Pp
 104 All data contained in
 105 .Fa a
 106 that is marked as dynamically allocated is freed,
 107 and the respective fields of
 108 .Fa a
 109 become empty.
 110 Contained data not marked as dynamically allocated remains intact.
 111 .Pp
 112 If the object
 113 .Fa a
 114 itself is marked as dynamically allocated, it is freed.
 115 Otherwise, the pointer
 116 .Fa a
 117 remains valid.
 118 .Pp
 119 If
 120 .Fa a
 121 is a
 122 .Dv NULL
 123 pointer or if neither the object itself nor any of its content
 124 is marked as dynamically allocated, no action occurs.
 125 .Sh RETURN VALUES
 126 If the allocation fails,
 127 .Fn ASN1_OBJECT_new
 128 returns
 129 .Dv NULL
 130 and sets an error code that can be obtained by
 131 .Xr ERR_get_error 3 .
 132 Otherwise it returns a pointer to the new object.
 133 .Sh SEE ALSO
 134 .Xr d2i_ASN1_OBJECT 3 ,
 135 .Xr OBJ_nid2obj 3
 136 .Sh HISTORY
 137 .Fn ASN1_OBJECT_new
 138 and
 139 .Fn ASN1_OBJECT_free
 140 appeared in SSLeay 0.8.1b or earlier and have been available since
 141 .Ox 2.4 .