Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / 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