secure/lib/libcrypto/man/ASN1_INTEGER_get_int64.3

   1 .\" Automatically generated by Pod::Man 4.09 (Pod::Simple 3.35)
   2 .\"
   3 .\" Standard preamble:
   4 .\" ========================================================================
   5 .de Sp \" Vertical space (when we can't use .PP)
   6 .if t .sp .5v
   7 .if n .sp
   8 ..
   9 .de Vb \" Begin verbatim text
  10 .ft CW
  11 .nf
  12 .ne \\$1
  13 ..
  14 .de Ve \" End verbatim text
  15 .ft R
  16 .fi
  17 ..
  18 .\" Set up some character translations and predefined strings.  \*(-- will
  19 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  20 .\" double quote, and \*(R" will give a right double quote.  \*(C+ will
  21 .\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
  22 .\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
  23 .\" nothing in troff, for use with C<>.
  24 .tr \(*W-
  25 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  26 .ie n \{\
  27 .    ds -- \(*W-
  28 .    ds PI pi
  29 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  30 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  31 .    ds L" ""
  32 .    ds R" ""
  33 .    ds C` ""
  34 .    ds C' ""
  35 'br\}
  36 .el\{\
  37 .    ds -- \|\(em\|
  38 .    ds PI \(*p
  39 .    ds L" ``
  40 .    ds R" ''
  41 .    ds C`
  42 .    ds C'
  43 'br\}
  44 .\"
  45 .\" Escape single quotes in literal strings from groff's Unicode transform.
  46 .ie \n(.g .ds Aq \(aq
  47 .el       .ds Aq '
  48 .\"
  49 .\" If the F register is >0, we'll generate index entries on stderr for
  50 .\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
  51 .\" entries marked with X<> in POD.  Of course, you'll have to process the
  52 .\" output yourself in some meaningful fashion.
  53 .\"
  54 .\" Avoid warning from groff about undefined register 'F'.
  55 .de IX
  56 ..
  57 .if !\nF .nr F 0
  58 .if \nF>0 \{\
  59 .    de IX
  60 .    tm Index:\\$1\t\\n%\t"\\$2"
  61 ..
  62 .    if !\nF==2 \{\
  63 .        nr % 0
  64 .        nr F 2
  65 .    \}
  66 .\}
  67 .\"
  68 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  69 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  70 .    \" fudge factors for nroff and troff
  71 .if n \{\
  72 .    ds #H 0
  73 .    ds #V .8m
  74 .    ds #F .3m
  75 .    ds #[ \f1
  76 .    ds #] \fP
  77 .\}
  78 .if t \{\
  79 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  80 .    ds #V .6m
  81 .    ds #F 0
  82 .    ds #[ \&
  83 .    ds #] \&
  84 .\}
  85 .    \" simple accents for nroff and troff
  86 .if n \{\
  87 .    ds ' \&
  88 .    ds ` \&
  89 .    ds ^ \&
  90 .    ds , \&
  91 .    ds ~ ~
  92 .    ds /
  93 .\}
  94 .if t \{\
  95 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
  96 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
  97 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
  98 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
  99 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 100 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 101 .\}
 102 .    \" troff and (daisy-wheel) nroff accents
 103 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 104 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 105 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 106 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 107 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 108 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 109 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 110 .ds ae a\h'-(\w'a'u*4/10)'e
 111 .ds Ae A\h'-(\w'A'u*4/10)'E
 112 .    \" corrections for vroff
 113 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 114 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 115 .    \" for low resolution devices (crt and lpr)
 116 .if \n(.H>23 .if \n(.V>19 \
 117 \{\
 118 .    ds : e
 119 .    ds 8 ss
 120 .    ds o a
 121 .    ds d- d\h'-1'\(ga
 122 .    ds D- D\h'-1'\(hy
 123 .    ds th \o'bp'
 124 .    ds Th \o'LP'
 125 .    ds ae ae
 126 .    ds Ae AE
 127 .\}
 128 .rm #[ #] #H #V #F C
 129 .\" ========================================================================
 130 .\"
 131 .IX Title "ASN1_INTEGER_GET_INT64 3"
 132 .TH ASN1_INTEGER_GET_INT64 3 "2018-11-20" "1.1.1a" "OpenSSL"
 133 .\" For nroff, turn off justification.  Always turn off hyphenation; it makes
 134 .\" way too many mistakes in technical documents.
 135 .if n .ad l
 136 .nh
 137 .SH "NAME"
 138 ASN1_INTEGER_get_uint64, ASN1_INTEGER_set_uint64, ASN1_INTEGER_get_int64, ASN1_INTEGER_get, ASN1_INTEGER_set_int64, ASN1_INTEGER_set, BN_to_ASN1_INTEGER, ASN1_INTEGER_to_BN, ASN1_ENUMERATED_get_int64, ASN1_ENUMERATED_get, ASN1_ENUMERATED_set_int64, ASN1_ENUMERATED_set, BN_to_ASN1_ENUMERATED, ASN1_ENUMERATED_to_BN \&\- ASN.1 INTEGER and ENUMERATED utilities
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/asn1.h>
 143 \&
 144 \& int ASN1_INTEGER_get_int64(int64_t *pr, const ASN1_INTEGER *a);
 145 \& long ASN1_INTEGER_get(const ASN1_INTEGER *a);
 146 \&
 147 \& int ASN1_INTEGER_set_int64(ASN1_INTEGER *a, int64_t r);
 148 \& int ASN1_INTEGER_set(const ASN1_INTEGER *a, long v);
 149 \&
 150 \& int ASN1_INTEGER_get_uint64(uint64_t *pr, const ASN1_INTEGER *a);
 151 \& int ASN1_INTEGER_set_uint64(ASN1_INTEGER *a, uint64_t r);
 152 \&
 153 \& ASN1_INTEGER *BN_to_ASN1_INTEGER(const BIGNUM *bn, ASN1_INTEGER *ai);
 154 \& BIGNUM *ASN1_INTEGER_to_BN(const ASN1_INTEGER *ai, BIGNUM *bn);
 155 \&
 156 \& int ASN1_ENUMERATED_get_int64(int64_t *pr, const ASN1_INTEGER *a);
 157 \& long ASN1_ENUMERATED_get(const ASN1_ENUMERATED *a);
 158 \&
 159 \& int ASN1_ENUMERATED_set_int64(ASN1_INTEGER *a, int64_t r);
 160 \& int ASN1_ENUMERATED_set(ASN1_ENUMERATED *a, long v);
 161 \&
 162 \& ASN1_ENUMERATED *BN_to_ASN1_ENUMERATED(BIGNUM *bn, ASN1_ENUMERATED *ai);
 163 \& BIGNUM *ASN1_ENUMERATED_to_BN(ASN1_ENUMERATED *ai, BIGNUM *bn);
 164 .Ve
 165 .SH "DESCRIPTION"
 166 .IX Header "DESCRIPTION"
 167 These functions convert to and from \fB\s-1ASN1_INTEGER\s0\fR and \fB\s-1ASN1_ENUMERATED\s0\fR
 168 structures.
 169 .PP
 170 \&\fIASN1_INTEGER_get_int64()\fR converts an \fB\s-1ASN1_INTEGER\s0\fR into an \fBint64_t\fR type
 171 If successful it returns 1 and sets \fB*pr\fR to the value of \fBa\fR. If it fails
 172 (due to invalid type or the value being too big to fit into an \fBint64_t\fR type)
 173 it returns 0.
 174 .PP
 175 \&\fIASN1_INTEGER_get_uint64()\fR is similar to \fIASN1_INTEGER_get_int64_t()\fR except it
 176 converts to a \fBuint64_t\fR type and an error is returned if the passed integer
 177 is negative.
 178 .PP
 179 \&\fIASN1_INTEGER_get()\fR also returns the value of \fBa\fR but it returns 0 if \fBa\fR is
 180 \&\s-1NULL\s0 and \-1 on error (which is ambiguous because \-1 is a legitimate value for
 181 an \fB\s-1ASN1_INTEGER\s0\fR). New applications should use \fIASN1_INTEGER_get_int64()\fR
 182 instead.
 183 .PP
 184 \&\fIASN1_INTEGER_set_int64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the
 185 \&\fBint64_t\fR value \fBr\fR.
 186 .PP
 187 \&\fIASN1_INTEGER_set_uint64()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the
 188 \&\fBuint64_t\fR value \fBr\fR.
 189 .PP
 190 \&\fIASN1_INTEGER_set()\fR sets the value of \fB\s-1ASN1_INTEGER\s0\fR \fBa\fR to the \fBlong\fR value
 191 \&\fBv\fR.
 192 .PP
 193 \&\fIBN_to_ASN1_INTEGER()\fR converts \fB\s-1BIGNUM\s0\fR \fBbn\fR to an \fB\s-1ASN1_INTEGER\s0\fR. If \fBai\fR
 194 is \s-1NULL\s0 a new \fB\s-1ASN1_INTEGER\s0\fR structure is returned. If \fBai\fR is not \s-1NULL\s0 then
 195 the existing structure will be used instead.
 196 .PP
 197 \&\fIASN1_INTEGER_to_BN()\fR converts \s-1ASN1_INTEGER\s0 \fBai\fR into a \fB\s-1BIGNUM\s0\fR. If \fBbn\fR is
 198 \&\s-1NULL\s0 a new \fB\s-1BIGNUM\s0\fR structure is returned. If \fBbn\fR is not \s-1NULL\s0 then the
 199 existing structure will be used instead.
 200 .PP
 201 \&\fIASN1_ENUMERATED_get_int64()\fR, \fIASN1_ENUMERATED_set_int64()\fR,
 202 \&\fIASN1_ENUMERATED_set()\fR, \fIBN_to_ASN1_ENUMERATED()\fR and \fIASN1_ENUMERATED_to_BN()\fR
 203 behave in an identical way to their \s-1ASN1_INTEGER\s0 counterparts except they
 204 operate on an \fB\s-1ASN1_ENUMERATED\s0\fR value.
 205 .PP
 206 \&\fIASN1_ENUMERATED_get()\fR returns the value of \fBa\fR in a similar way to
 207 \&\fIASN1_INTEGER_get()\fR but it returns \fB0xffffffffL\fR if the value of \fBa\fR will not
 208 fit in a long type. New applications should use \fIASN1_ENUMERATED_get_int64()\fR
 209 instead.
 210 .SH "NOTES"
 211 .IX Header "NOTES"
 212 In general an \fB\s-1ASN1_INTEGER\s0\fR or \fB\s-1ASN1_ENUMERATED\s0\fR type can contain an
 213 integer of almost arbitrary size and so cannot always be represented by a C
 214 \&\fBint64_t\fR type. However in many cases (for example version numbers) they
 215 represent small integers which can be more easily manipulated if converted to
 216 an appropriate C integer type.
 217 .SH "BUGS"
 218 .IX Header "BUGS"
 219 The ambiguous return values of \fIASN1_INTEGER_get()\fR and \fIASN1_ENUMERATED_get()\fR
 220 mean these functions should be avoided if possible. They are retained for
 221 compatibility. Normally the ambiguous return values are not legitimate
 222 values for the fields they represent.
 223 .SH "RETURN VALUES"
 224 .IX Header "RETURN VALUES"
 225 \&\fIASN1_INTEGER_set_int64()\fR, \fIASN1_INTEGER_set()\fR, \fIASN1_ENUMERATED_set_int64()\fR and
 226 \&\fIASN1_ENUMERATED_set()\fR return 1 for success and 0 for failure. They will only
 227 fail if a memory allocation error occurs.
 228 .PP
 229 \&\fIASN1_INTEGER_get_int64()\fR and \fIASN1_ENUMERATED_get_int64()\fR return 1 for success
 230 and 0 for failure. They will fail if the passed type is incorrect (this will
 231 only happen if there is a programming error) or if the value exceeds the range
 232 of an \fBint64_t\fR type.
 233 .PP
 234 \&\fIBN_to_ASN1_INTEGER()\fR and \fIBN_to_ASN1_ENUMERATED()\fR return an \fB\s-1ASN1_INTEGER\s0\fR or
 235 \&\fB\s-1ASN1_ENUMERATED\s0\fR structure respectively or \s-1NULL\s0 if an error occurs. They will
 236 only fail due to a memory allocation error.
 237 .PP
 238 \&\fIASN1_INTEGER_to_BN()\fR and \fIASN1_ENUMERATED_to_BN()\fR return a \fB\s-1BIGNUM\s0\fR structure
 239 of \s-1NULL\s0 if an error occurs. They can fail if the passed type is incorrect
 240 (due to programming error) or due to a memory allocation failure.
 241 .SH "SEE ALSO"
 242 .IX Header "SEE ALSO"
 243 \&\fIERR_get_error\fR\|(3)
 244 .SH "HISTORY"
 245 .IX Header "HISTORY"
 246 \&\fIASN1_INTEGER_set_int64()\fR, \fIASN1_INTEGER_get_int64()\fR,
 247 \&\fIASN1_ENUMERATED_set_int64()\fR and \fIASN1_ENUMERATED_get_int64()\fR
 248 were added to OpenSSL 1.1.0.
 249 .SH "COPYRIGHT"
 250 .IX Header "COPYRIGHT"
 251 Copyright 2015\-2018 The OpenSSL Project Authors. All Rights Reserved.
 252 .PP
 253 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 254 this file except in compliance with the License.  You can obtain a copy
 255 in the file \s-1LICENSE\s0 in the source distribution or at
 256 <https://www.openssl.org/source/license.html>.