Commit manual pages after running 'man-update' and add new manual pages.
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_STRING_length.3
CommitLineData
74dab6c2
JR
1.rn '' }`
2''' $RCSfile$$Revision$$Date$
3'''
4''' $Log$
5'''
6.de Sh
984263bc
MD
7.br
8.if t .Sp
9.ne 5
10.PP
11\fB\\$1\fR
12.PP
13..
74dab6c2 14.de Sp
984263bc
MD
15.if t .sp .5v
16.if n .sp
17..
74dab6c2 18.de Ip
984263bc
MD
19.br
20.ie \\n(.$>=3 .ne \\$3
21.el .ne 3
22.IP "\\$1" \\$2
23..
74dab6c2 24.de Vb
984263bc
MD
25.ft CW
26.nf
27.ne \\$1
28..
74dab6c2 29.de Ve
984263bc
MD
30.ft R
31
32.fi
33..
74dab6c2
JR
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'''
984263bc 40.tr \(*W-|\(bv\*(Tr
984263bc 41.ie n \{\
74dab6c2
JR
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' '
984263bc
MD
62'br\}
63.el\{\
74dab6c2
JR
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
984263bc 79'br\}
74dab6c2
JR
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"
984263bc 92..
74dab6c2
JR
93.nr % 0
94.rr F
984263bc 95.\}
74dab6c2
JR
96.TH ASN1_STRING_length 3 "0.9.7d" "2/Sep/2004" "OpenSSL"
97.UC
98.if n .hy 0
984263bc 99.if n .na
74dab6c2
JR
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
984263bc 112.bd B 3
74dab6c2 113. \" fudge factors for nroff and troff
984263bc 114.if n \{\
74dab6c2
JR
115. ds #H 0
116. ds #V .8m
117. ds #F .3m
118. ds #[ \f1
119. ds #] \fP
984263bc
MD
120.\}
121.if t \{\
74dab6c2
JR
122. ds #H ((1u-(\\\\n(.fu%2u))*.13m)
123. ds #V .6m
124. ds #F 0
125. ds #[ \&
126. ds #] \&
984263bc 127.\}
74dab6c2 128. \" simple accents for nroff and troff
984263bc 129.if n \{\
74dab6c2
JR
130. ds ' \&
131. ds ` \&
132. ds ^ \&
133. ds , \&
134. ds ~ ~
135. ds ? ?
136. ds ! !
137. ds /
138. ds q
984263bc
MD
139.\}
140.if t \{\
74dab6c2
JR
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'
984263bc 150.\}
74dab6c2 151. \" troff and (daisy-wheel) nroff accents
984263bc
MD
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'
74dab6c2
JR
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'\*(#]
984263bc
MD
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
74dab6c2
JR
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
984263bc
MD
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'
74dab6c2 170. \" for low resolution devices (crt and lpr)
984263bc
MD
171.if \n(.H>23 .if \n(.V>19 \
172\{\
74dab6c2
JR
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
984263bc
MD
188.\}
189.rm #[ #] #H #V #F C
984263bc
MD
190.SH "NAME"
191ASN1_STRING_dup, ASN1_STRING_cmp, ASN1_STRING_set, ASN1_STRING_length,
192ASN1_STRING_length_set, ASN1_STRING_type, ASN1_STRING_data \-
74dab6c2 193ASN1_STRING utility functions
984263bc 194.SH "SYNOPSIS"
74dab6c2 195.PP
984263bc
MD
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"
74dab6c2 216These functions allow an \fBASN1_STRING\fR structure to be manipulated.
984263bc 217.PP
74dab6c2 218\fIASN1_STRING_length()\fR returns the length of the content of \fBx\fR.
984263bc 219.PP
74dab6c2 220\fIASN1_STRING_data()\fR returns an internal pointer to the data of \fBx\fR.
984263bc
MD
221Since this is an internal pointer it should \fBnot\fR be freed or
222modified in any way.
223.PP
74dab6c2 224\fIASN1_STRING_dup()\fR returns a copy of the structure \fBa\fR.
984263bc 225.PP
74dab6c2 226\fIASN1_STRING_cmp()\fR compares \fBa\fR and \fBb\fR returning 0 if the two
984263bc
MD
227are identical. The string types and content are compared.
228.PP
74dab6c2
JR
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
231is \-1 then the length is determined by \fIstrlen\fR\|(data).
984263bc 232.PP
74dab6c2 233\fIASN1_STRING_type()\fR returns the type of \fBx\fR, using standard constants
984263bc
MD
234such as \fBV_ASN1_OCTET_STRING\fR.
235.PP
74dab6c2 236\fIASN1_STRING_to_UTF8()\fR converts the string \fBin\fR to UTF8 format, the
984263bc 237converted data is allocated in a buffer in \fB*out\fR. The length of
74dab6c2 238\fBout\fR is returned or a negative error code. The buffer \fB*out\fR
984263bc
MD
239should be free using \fIOPENSSL_free()\fR.
240.SH "NOTES"
74dab6c2
JR
241Almost all ASN1 types in OpenSSL are represented as an \fBASN1_STRING\fR
242structure. Other types such as \fBASN1_OCTET_STRING\fR are simply typedefed
243to \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
984263bc 245entirely of primitive string types such as \fBDirectoryString\fR and
74dab6c2 246\fBTime\fR.
984263bc 247.PP
74dab6c2
JR
248These functions should \fBnot\fR be used to examine or modify \fBASN1_INTEGER\fR
249or \fBASN1_ENUMERATED\fR types: the relevant \fBINTEGER\fR or \fBENUMERATED\fR
984263bc
MD
250utility functions should be used instead.
251.PP
252In general it cannot be assumed that the data returned by \fIASN1_STRING_data()\fR
253is null terminated or does not contain embedded nulls. The actual format
254of the data will depend on the actual string type itself: for example
74dab6c2
JR
255for and IA5String the data will be ASCII, for a BMPString two bytes per
256character in big endian format, UTF8String will be in UTF8 format.
984263bc
MD
257.PP
258Similar care should be take to ensure the data is in the correct format
259when calling \fIASN1_STRING_set()\fR.
260.SH "RETURN VALUES"
984263bc 261.SH "SEE ALSO"
984263bc
MD
262ERR_get_error(3)
263.SH "HISTORY"
74dab6c2
JR
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,
268ASN1_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
984263bc 282.IX Header "HISTORY"
74dab6c2 283