secure/lib/libcrypto/man/ASN1_STRING_length.3

   1 .rn '' }`
   2 ''' $RCSfile$$Revision$$Date$
   3 '''
   4 ''' $Log$
   5 '''
   6 .de Sh
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve
  30 .ft R
  31
  32 .fi
  33 ..
  34 '''
  35 '''
  36 '''     Set up \*(-- to give an unbreakable dash;
  37 '''     string Tr holds user defined translation string.
  38 '''     Bell System Logo is used as a dummy character.
  39 '''
  40 .tr \(*W-|\(bv\*(Tr
  41 .ie n \{\
  42 .ds -- \(*W-
  43 .ds PI pi
  44 .if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  45 .if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch
  46 .ds L" ""
  47 .ds R" ""
  48 '''   \*(M", \*(S", \*(N" and \*(T" are the equivalent of
  49 '''   \*(L" and \*(R", except that they are used on ".xx" lines,
  50 '''   such as .IP and .SH, which do another additional levels of
  51 '''   double-quote interpretation
  52 .ds M" """
  53 .ds S" """
  54 .ds N" """""
  55 .ds T" """""
  56 .ds L' '
  57 .ds R' '
  58 .ds M' '
  59 .ds S' '
  60 .ds N' '
  61 .ds T' '
  62 'br\}
  63 .el\{\
  64 .ds -- \(em\|
  65 .tr \*(Tr
  66 .ds L" ``
  67 .ds R" ''
  68 .ds M" ``
  69 .ds S" ''
  70 .ds N" ``
  71 .ds T" ''
  72 .ds L' `
  73 .ds R' '
  74 .ds M' `
  75 .ds S' '
  76 .ds N' `
  77 .ds T' '
  78 .ds PI \(*p
  79 'br\}
  80 .\"     If the F register is turned on, we'll generate
  81 .\"     index entries out stderr for the following things:
  82 .\"             TH      Title
  83 .\"             SH      Header
  84 .\"             Sh      Subsection
  85 .\"             Ip      Item
  86 .\"             X<>     Xref  (embedded
  87 .\"     Of course, you have to process the output yourself
  88 .\"     in some meaninful fashion.
  89 .if \nF \{
  90 .de IX
  91 .tm Index:\\$1\t\\n%\t"\\$2"
  92 ..
  93 .nr % 0
  94 .rr F
  95 .\}
  96 .TH ASN1_STRING_length 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
  97 .UC
  98 .if n .hy 0
  99 .if n .na
 100 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
 101 .de CQ          \" put $1 in typewriter font
 102 .ft CW
 103 'if n "\c
 104 'if t \\&\\$1\c
 105 'if n \\&\\$1\c
 106 'if n \&"
 107 \\&\\$2 \\$3 \\$4 \\$5 \\$6 \\$7
 108 '.ft R
 109 ..
 110 .\" @(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2
 111 .       \" AM - accent mark definitions
 112 .bd B 3
 113 .       \" fudge factors for nroff and troff
 114 .if n \{\
 115 .       ds #H 0
 116 .       ds #V .8m
 117 .       ds #F .3m
 118 .       ds #[ \f1
 119 .       ds #] \fP
 120 .\}
 121 .if t \{\
 122 .       ds #H ((1u-(\\\\n(.fu%2u))*.13m)
 123 .       ds #V .6m
 124 .       ds #F 0
 125 .       ds #[ \&
 126 .       ds #] \&
 127 .\}
 128 .       \" simple accents for nroff and troff
 129 .if n \{\
 130 .       ds ' \&
 131 .       ds ` \&
 132 .       ds ^ \&
 133 .       ds , \&
 134 .       ds ~ ~
 135 .       ds ? ?
 136 .       ds ! !
 137 .       ds /
 138 .       ds q
 139 .\}
 140 .if t \{\
 141 .       ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 142 .       ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 143 .       ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 144 .       ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 145 .       ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 146 .       ds ? \s-2c\h'-\w'c'u*7/10'\u\h'\*(#H'\zi\d\s+2\h'\w'c'u*8/10'
 147 .       ds ! \s-2\(or\s+2\h'-\w'\(or'u'\v'-.8m'.\v'.8m'
 148 .       ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 149 .       ds q o\h'-\w'o'u*8/10'\s-4\v'.4m'\z\(*i\v'-.4m'\s+4\h'\w'o'u*8/10'
 150 .\}
 151 .       \" troff and (daisy-wheel) nroff accents
 152 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 153 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 154 .ds v \\k:\h'-(\\n(.wu*9/10-\*(#H)'\v'-\*(#V'\*(#[\s-4v\s0\v'\*(#V'\h'|\\n:u'\*(#]
 155 .ds _ \\k:\h'-(\\n(.wu*9/10-\*(#H+(\*(#F*2/3))'\v'-.4m'\z\(hy\v'.4m'\h'|\\n:u'
 156 .ds . \\k:\h'-(\\n(.wu*8/10)'\v'\*(#V*4/10'\z.\v'-\*(#V*4/10'\h'|\\n:u'
 157 .ds 3 \*(#[\v'.2m'\s-2\&3\s0\v'-.2m'\*(#]
 158 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 159 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 160 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 161 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 162 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 163 .ds ae a\h'-(\w'a'u*4/10)'e
 164 .ds Ae A\h'-(\w'A'u*4/10)'E
 165 .ds oe o\h'-(\w'o'u*4/10)'e
 166 .ds Oe O\h'-(\w'O'u*4/10)'E
 167 .       \" corrections for vroff
 168 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 169 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 170 .       \" for low resolution devices (crt and lpr)
 171 .if \n(.H>23 .if \n(.V>19 \
 172 \{\
 173 .       ds : e
 174 .       ds 8 ss
 175 .       ds v \h'-1'\o'\(aa\(ga'
 176 .       ds _ \h'-1'^
 177 .       ds . \h'-1'.
 178 .       ds 3 3
 179 .       ds o a
 180 .       ds d- d\h'-1'\(ga
 181 .       ds D- D\h'-1'\(hy
 182 .       ds th \o'bp'
 183 .       ds Th \o'LP'
 184 .       ds ae ae
 185 .       ds Ae AE
 186 .       ds oe oe
 187 .       ds Oe OE
 188 .\}
 189 .rm #[ #] #H #V #F C
 190 .SH "NAME"
 191 ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
 192 ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data \-
 193 ASN1_STRING utility functions
 194 .SH "SYNOPSIS"
 195 .PP
 196 .Vb 2
 197 \& int ASN1_STRING_length(ASN1_STRING *x);
 198 \& unsigned char * ASN1_STRING_data(ASN1_STRING *x);
 199 .Ve
 200 .Vb 1
 201 \& ASN1_STRING * ASN1_STRING_dup(ASN1_STRING *a);
 202 .Ve
 203 .Vb 1
 204 \& int ASN1_STRING_cmp(ASN1_STRING *a, ASN1_STRING *b);
 205 .Ve
 206 .Vb 1
 207 \& int ASN1_STRING_set(ASN1_STRING *str, const void *data, int len);
 208 .Ve
 209 .Vb 1
 210 \& int ASN1_STRING_type(ASN1_STRING *x);
 211 .Ve
 212 .Vb 1
 213 \& int ASN1_STRING_to_UTF8(unsigned char **out, ASN1_STRING *in);
 214 .Ve
 215 .SH "DESCRIPTION"
 216 These functions allow an \fBASN1_STRING\fR structure to be manipulated.
 217 .PP
 218 \fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
 219 .PP
 220 \fIASN1_STRING_data()\fR returns an internal pointer to the data of \fBx\fR.
 221 Since this is an internal pointer it should \fBnot\fR be freed or
 222 modified in any way.
 223 .PP
 224 \fIASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
 225 .PP
 226 \fIASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
 227 are identical. The string types and content are compared.
 228 .PP
 229 \fIASN1_STRING_set()\fR sets the data of string \fBstr\fR to the buffer
 230 \fBdata\fR or length \fBlen\fR. The supplied data is copied. If \fBlen\fR
 231 is \-1 then the length is determined by \fIstrlen\fR\|(data).
 232 .PP
 233 \fIASN1_STRING_type()\fR returns the type of \fBx\fR, using standard constants
 234 such as \fBV_ASN1_OCTET_STRING\fR.
 235 .PP
 236 \fIASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to UTF8 format, the
 237 converted data is allocated in a buffer in \fB*out\fR. The length of
 238 \fBout\fR is returned or a negative error code. The buffer \fB*out\fR
 239 should be free using \fIOPENSSL_free()\fR.
 240 .SH "NOTES"
 241 Almost all ASN1 types in OpenSSL are represented as an \fBASN1_STRING\fR
 242 structure. Other types such as \fBASN1_OCTET_STRING\fR are simply typedefed
 243 to \fBASN1_STRING\fR and the functions call the \fBASN1_STRING\fR equivalents.
 244 \fBASN1_STRING\fR is also used for some \fBCHOICE\fR types which consist
 245 entirely of primitive string types such as \fBDirectoryString\fR and
 246 \fBTime\fR.
 247 .PP
 248 These functions should \fBnot\fR be used to examine or modify \fBASN1_INTEGER\fR
 249 or \fBASN1_ENUMERATED\fR types: the relevant \fBINTEGER\fR or \fBENUMERATED\fR
 250 utility functions should be used instead.
 251 .PP
 252 In general it cannot be assumed that the data returned by \fIASN1_STRING_data()\fR
 253 is null terminated or does not contain embedded nulls. The actual format
 254 of the data will depend on the actual string type itself: for example
 255 for and IA5String the data will be ASCII, for a BMPString two bytes per
 256 character in big endian format, UTF8String will be in UTF8 format.
 257 .PP
 258 Similar care should be take to ensure the data is in the correct format
 259 when calling \fIASN1_STRING_set()\fR.
 260 .SH "RETURN VALUES"
 261 .SH "SEE ALSO"
 262 ERR_get_error(3)
 263 .SH "HISTORY"
 264
 265 .rn }` ''
 266 .IX Title "ASN1_STRING_length 3"
 267 .IX Name "ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
 268 ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data - ASN1_STRING utility functions"
 269
 270 .IX Header "NAME"
 271
 272 .IX Header "SYNOPSIS"
 273
 274 .IX Header "DESCRIPTION"
 275
 276 .IX Header "NOTES"
 277
 278 .IX Header "RETURN VALUES"
 279
 280 .IX Header "SEE ALSO"
 281
 282 .IX Header "HISTORY"
 283