secure/lib/libcrypto/man/ASN1_STRING_length.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_STRING_LENGTH 3"
 132 .TH ASN1_STRING_LENGTH 3 "2018-09-11" "1.1.1" "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_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length, ASN1_STRING_type, ASN1_STRING_get0_data, ASN1_STRING_data, ASN1_STRING_to_UTF8 \- ASN1_STRING utility functions
 139 .SH "SYNOPSIS"
 140 .IX Header "SYNOPSIS"
 141 .Vb 1
 142 \& #include <openssl/asn1.h>
 143 \&
 144 \& int ASN1_STRING_length(ASN1_STRING *x);
 145 \& const unsigned char * ASN1_STRING_get0_data(const ASN1_STRING *x);
 146 \& unsigned char * ASN1_STRING_data(ASN1_STRING *x);
 147 \&
 148 \& ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
 149 \&
 150 \& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
 151 \&
 152 \& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
 153 \&
 154 \& int ASN1_STRING_type(const ASN1_STRING *x);
 155 \&
 156 \& int ASN1_STRING_to_UTF8(unsigned char **out, const ASN1_STRING *in);
 157 .Ve
 158 .SH "DESCRIPTION"
 159 .IX Header "DESCRIPTION"
 160 These functions allow an \fB\s-1ASN1_STRING\s0\fR structure to be manipulated.
 161 .PP
 162 \&\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
 163 .PP
 164 \&\fIASN1_STRING_get0_data()\fR returns an internal pointer to the data of \fBx\fR.
 165 Since this is an internal pointer it should \fBnot\fR be freed or
 166 modified in any way.
 167 .PP
 168 \&\fIASN1_STRING_data()\fR is similar to \fIASN1_STRING_get0_data()\fR except the
 169 returned value is not constant. This function is deprecated:
 170 applications should use \fIASN1_STRING_get0_data()\fR instead.
 171 .PP
 172 \&\fIASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
 173 .PP
 174 \&\fIASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
 175 are identical. The string types and content are compared.
 176 .PP
 177 \&\fIASN1_STRING_set()\fR sets the data of string \fBstr\fR to the buffer
 178 \&\fBdata\fR or length \fBlen\fR. The supplied data is copied. If \fBlen\fR
 179 is \-1 then the length is determined by strlen(data).
 180 .PP
 181 \&\fIASN1_STRING_type()\fR returns the type of \fBx\fR, using standard constants
 182 such as \fBV_ASN1_OCTET_STRING\fR.
 183 .PP
 184 \&\fIASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to \s-1UTF8\s0 format, the
 185 converted data is allocated in a buffer in \fB*out\fR. The length of
 186 \&\fBout\fR is returned or a negative error code. The buffer \fB*out\fR
 187 should be freed using \fIOPENSSL_free()\fR.
 188 .SH "NOTES"
 189 .IX Header "NOTES"
 190 Almost all \s-1ASN1\s0 types in OpenSSL are represented as an \fB\s-1ASN1_STRING\s0\fR
 191 structure. Other types such as \fB\s-1ASN1_OCTET_STRING\s0\fR are simply typedef'ed
 192 to \fB\s-1ASN1_STRING\s0\fR and the functions call the \fB\s-1ASN1_STRING\s0\fR equivalents.
 193 \&\fB\s-1ASN1_STRING\s0\fR is also used for some \fB\s-1CHOICE\s0\fR types which consist
 194 entirely of primitive string types such as \fBDirectoryString\fR and
 195 \&\fBTime\fR.
 196 .PP
 197 These functions should \fBnot\fR be used to examine or modify \fB\s-1ASN1_INTEGER\s0\fR
 198 or \fB\s-1ASN1_ENUMERATED\s0\fR types: the relevant \fB\s-1INTEGER\s0\fR or \fB\s-1ENUMERATED\s0\fR
 199 utility functions should be used instead.
 200 .PP
 201 In general it cannot be assumed that the data returned by \fIASN1_STRING_data()\fR
 202 is null terminated or does not contain embedded nulls. The actual format
 203 of the data will depend on the actual string type itself: for example
 204 for an IA5String the data will be \s-1ASCII,\s0 for a BMPString two bytes per
 205 character in big endian format, and for an UTF8String it will be in \s-1UTF8\s0 format.
 206 .PP
 207 Similar care should be take to ensure the data is in the correct format
 208 when calling \fIASN1_STRING_set()\fR.
 209 .SH "RETURN VALUES"
 210 .IX Header "RETURN VALUES"
 211 \&\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
 212 .PP
 213 \&\fIASN1_STRING_get0_data()\fR and \fIASN1_STRING_data()\fR return an internal pointer to
 214 the data of \fBx\fR.
 215 .PP
 216 \&\fIASN1_STRING_dup()\fR returns a valid \fB\s-1ASN1_STRING\s0\fR structure or \fB\s-1NULL\s0\fR if an
 217 error occurred.
 218 .PP
 219 \&\fIASN1_STRING_cmp()\fR returns an integer greater than, equal to, or less than 0,
 220 according to whether \fBa\fR is greater than, equal to, or less than \fBb\fR.
 221 .PP
 222 \&\fIASN1_STRING_set()\fR returns 1 on success or 0 on error.
 223 .PP
 224 \&\fIASN1_STRING_type()\fR returns the type of \fBx\fR.
 225 .PP
 226 \&\fIASN1_STRING_to_UTF8()\fR returns the number of bytes in output string \fBout\fR or a
 227 negative value if an error occurred.
 228 .SH "SEE ALSO"
 229 .IX Header "SEE ALSO"
 230 \&\fIERR_get_error\fR\|(3)
 231 .SH "COPYRIGHT"
 232 .IX Header "COPYRIGHT"
 233 Copyright 2002\-2018 The OpenSSL Project Authors. All Rights Reserved.
 234 .PP
 235 Licensed under the OpenSSL license (the \*(L"License\*(R").  You may not use
 236 this file except in compliance with the License.  You can obtain a copy
 237 in the file \s-1LICENSE\s0 in the source distribution or at
 238 <https://www.openssl.org/source/license.html>.