Switch from OpenSSL 0.9.7d to 0.9.7e.
[dragonfly.git] / secure / lib / libcrypto / man / ASN1_STRING_print_ex.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_print_ex 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 190.SH "NAME"
74dab6c2 191ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp \- ASN1_STRING output routines.
984263bc 192.SH "SYNOPSIS"
74dab6c2 193.PP
984263bc
MD
194.Vb 1
195\& #include <openssl/asn1.h>
196.Ve
197.Vb 3
198\& int ASN1_STRING_print_ex(BIO *out, ASN1_STRING *str, unsigned long flags);
199\& int ASN1_STRING_print_ex_fp(FILE *fp, ASN1_STRING *str, unsigned long flags);
200\& int ASN1_STRING_print(BIO *out, ASN1_STRING *str);
201.Ve
202.SH "DESCRIPTION"
74dab6c2
JR
203These functions output an \fBASN1_STRING\fR structure. \fBASN1_STRING\fR is used to
204represent all the ASN1 string types.
984263bc 205.PP
74dab6c2 206\fIASN1_STRING_print_ex()\fR outputs \fBstr\fR to \fBout\fR, the format is determined by
984263bc
MD
207the options \fBflags\fR. \fIASN1_STRING_print_ex_fp()\fR is identical except it outputs
208to \fBfp\fR instead.
209.PP
74dab6c2
JR
210\fIASN1_STRING_print()\fR prints \fBstr\fR to \fBout\fR but using a different format to
211\fIASN1_STRING_print_ex()\fR. It replaces unprintable characters (other than CR, LF)
212with \*(L'.\*(R'.
984263bc 213.SH "NOTES"
74dab6c2 214\fIASN1_STRING_print()\fR is a legacy function which should be avoided in new applications.
984263bc 215.PP
74dab6c2
JR
216Although there are a large number of options frequently \fBASN1_STRFLAGS_RFC2253\fR is
217suitable, or on UTF8 terminals \fBASN1_STRFLAGS_RFC2253 & ~ASN1_STRFLAGS_ESC_MSB\fR.
984263bc
MD
218.PP
219The complete set of supported options for \fBflags\fR is listed below.
220.PP
74dab6c2
JR
221Various characters can be escaped. If \fBASN1_STRFLGS_ESC_2253\fR is set the characters
222determined by RFC2253 are escaped. If \fBASN1_STRFLGS_ESC_CTRL\fR is set control
223characters are escaped. If \fBASN1_STRFLGS_ESC_MSB\fR is set characters with the
224MSB set are escaped: this option should \fBnot\fR be used if the terminal correctly
225interprets UTF8 sequences.
984263bc
MD
226.PP
227Escaping takes several forms.
228.PP
229If the character being escaped is a 16 bit character then the form \*(L"\eWXXXX\*(R" is used
230using exactly four characters for the hex representation. If it is 32 bits then
74dab6c2
JR
231\*(L"\eUXXXXXXXX\*(R" is used using eight characters of its hex representation. These forms
232will only be used if UTF8 conversion is not set (see below).
984263bc 233.PP
74dab6c2
JR
234Printable characters are normally escaped using the backslash \*(L'\e\*(R' character. If
235\fBASN1_STRFLGS_ESC_QUOTE\fR is set then the whole string is instead surrounded by
984263bc
MD
236double quote characters: this is arguably more readable than the backslash
237notation. Other characters use the \*(L"\eXX\*(R" using exactly two characters of the hex
238representation.
239.PP
74dab6c2
JR
240If \fBASN1_STRFLGS_UTF8_CONVERT\fR is set then characters are converted to UTF8
241format first. If the terminal supports the display of UTF8 sequences then this
984263bc
MD
242option will correctly display multi byte characters.
243.PP
74dab6c2 244If \fBASN1_STRFLGS_IGNORE_TYPE\fR is set then the string type is not interpreted at
984263bc
MD
245all: everything is assumed to be one byte per character. This is primarily for
246debugging purposes and can result in confusing output in multi character strings.
247.PP
74dab6c2
JR
248If \fBASN1_STRFLGS_SHOW_TYPE\fR is set then the string type itself is printed out
249before its value (for example \*(L"BMPSTRING"), this actually uses \fIASN1_tag2str()\fR.
984263bc 250.PP
74dab6c2 251The content of a string instead of being interpreted can be \*(L"dumped": this just
984263bc
MD
252outputs the value of the string using the form #XXXX using hex format for each
253octet.
254.PP
74dab6c2 255If \fBASN1_STRFLGS_DUMP_ALL\fR is set then any type is dumped.
984263bc 256.PP
74dab6c2
JR
257Normally non character string types (such as OCTET STRING) are assumed to be
258one byte per character, if \fBASN1_STRFLAGS_DUMP_UNKNOWN\fR is set then they will
984263bc
MD
259be dumped instead.
260.PP
261When a type is dumped normally just the content octets are printed, if
74dab6c2 262\fBASN1_STRFLGS_DUMP_DER\fR is set then the complete encoding is dumped
984263bc
MD
263instead (including tag and length octets).
264.PP
74dab6c2 265\fBASN1_STRFLGS_RFC2253\fR includes all the flags required by RFC2253. It is
984263bc 266equivalent to:
74dab6c2
JR
267 ASN1_STRFLGS_ESC_2253 | ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB |
268 ASN1_STRFLGS_UTF8_CONVERT | ASN1_STRFLGS_DUMP_UNKNOWN ASN1_STRFLGS_DUMP_DER
984263bc 269.SH "SEE ALSO"
984263bc
MD
270X509_NAME_print_ex(3),
271ASN1_tag2str(3)
272.SH "HISTORY"
74dab6c2
JR
273TBA
274
275.rn }` ''
276.IX Title "ASN1_STRING_print_ex 3"
277.IX Name "ASN1_STRING_print_ex, ASN1_STRING_print_ex_fp - ASN1_STRING output routines."
278
279.IX Header "NAME"
280
281.IX Header "SYNOPSIS"
282
283.IX Header "DESCRIPTION"
284
285.IX Header "NOTES"
286
287.IX Header "SEE ALSO"
288
984263bc 289.IX Header "HISTORY"
74dab6c2 290