secure/lib/libcrypto/man/X509_NAME_print_ex.3

   1 .\" Automatically generated by Pod::Man version 1.15
   2 .\" Wed Feb 19 16:43:00 2003
   3 .\"
   4 .\" Standard preamble:
   5 .\" ======================================================================
   6 .de Sh \" Subsection heading
   7 .br
   8 .if t .Sp
   9 .ne 5
  10 .PP
  11 \fB\\$1\fR
  12 .PP
  13 ..
  14 .de Sp \" Vertical space (when we can't use .PP)
  15 .if t .sp .5v
  16 .if n .sp
  17 ..
  18 .de Ip \" List item
  19 .br
  20 .ie \\n(.$>=3 .ne \\$3
  21 .el .ne 3
  22 .IP "\\$1" \\$2
  23 ..
  24 .de Vb \" Begin verbatim text
  25 .ft CW
  26 .nf
  27 .ne \\$1
  28 ..
  29 .de Ve \" End verbatim text
  30 .ft R
  31
  32 .fi
  33 ..
  34 .\" Set up some character translations and predefined strings.  \*(-- will
  35 .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
  36 .\" double quote, and \*(R" will give a right double quote.  | will give a
  37 .\" real vertical bar.  \*(C+ will give a nicer C++.  Capital omega is used
  38 .\" to do unbreakable dashes and therefore won't be available.  \*(C` and
  39 .\" \*(C' expand to `' in nroff, nothing in troff, for use with C<>
  40 .tr \(*W-|\(bv\*(Tr
  41 .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
  42 .ie n \{\
  43 .    ds -- \(*W-
  44 .    ds PI pi
  45 .    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
  46 .    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
  47 .    ds L" ""
  48 .    ds R" ""
  49 .    ds C` ""
  50 .    ds C' ""
  51 'br\}
  52 .el\{\
  53 .    ds -- \|\(em\|
  54 .    ds PI \(*p
  55 .    ds L" ``
  56 .    ds R" ''
  57 'br\}
  58 .\"
  59 .\" If the F register is turned on, we'll generate index entries on stderr
  60 .\" for titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and
  61 .\" index entries marked with X<> in POD.  Of course, you'll have to process
  62 .\" the output yourself in some meaningful fashion.
  63 .if \nF \{\
  64 .    de IX
  65 .    tm Index:\\$1\t\\n%\t"\\$2"
  66 ..
  67 .    nr % 0
  68 .    rr F
  69 .\}
  70 .\"
  71 .\" For nroff, turn off justification.  Always turn off hyphenation; it
  72 .\" makes way too many mistakes in technical documents.
  73 .hy 0
  74 .if n .na
  75 .\"
  76 .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2).
  77 .\" Fear.  Run.  Save yourself.  No user-serviceable parts.
  78 .bd B 3
  79 .    \" fudge factors for nroff and troff
  80 .if n \{\
  81 .    ds #H 0
  82 .    ds #V .8m
  83 .    ds #F .3m
  84 .    ds #[ \f1
  85 .    ds #] \fP
  86 .\}
  87 .if t \{\
  88 .    ds #H ((1u-(\\\\n(.fu%2u))*.13m)
  89 .    ds #V .6m
  90 .    ds #F 0
  91 .    ds #[ \&
  92 .    ds #] \&
  93 .\}
  94 .    \" simple accents for nroff and troff
  95 .if n \{\
  96 .    ds ' \&
  97 .    ds ` \&
  98 .    ds ^ \&
  99 .    ds , \&
 100 .    ds ~ ~
 101 .    ds /
 102 .\}
 103 .if t \{\
 104 .    ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u"
 105 .    ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u'
 106 .    ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u'
 107 .    ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u'
 108 .    ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u'
 109 .    ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u'
 110 .\}
 111 .    \" troff and (daisy-wheel) nroff accents
 112 .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V'
 113 .ds 8 \h'\*(#H'\(*b\h'-\*(#H'
 114 .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#]
 115 .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H'
 116 .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u'
 117 .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#]
 118 .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#]
 119 .ds ae a\h'-(\w'a'u*4/10)'e
 120 .ds Ae A\h'-(\w'A'u*4/10)'E
 121 .    \" corrections for vroff
 122 .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u'
 123 .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u'
 124 .    \" for low resolution devices (crt and lpr)
 125 .if \n(.H>23 .if \n(.V>19 \
 126 \{\
 127 .    ds : e
 128 .    ds 8 ss
 129 .    ds o a
 130 .    ds d- d\h'-1'\(ga
 131 .    ds D- D\h'-1'\(hy
 132 .    ds th \o'bp'
 133 .    ds Th \o'LP'
 134 .    ds ae ae
 135 .    ds Ae AE
 136 .\}
 137 .rm #[ #] #H #V #F C
 138 .\" ======================================================================
 139 .\"
 140 .IX Title "X509_NAME_print_ex 3"
 141 .TH X509_NAME_print_ex 3 "0.9.7a" "2003-02-19" "OpenSSL"
 142 .UC
 143 .SH "NAME"
 144 X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
 145 X509_NAME_oneline \- X509_NAME printing routines.
 146 .SH "SYNOPSIS"
 147 .IX Header "SYNOPSIS"
 148 .Vb 1
 149 \& #include <openssl/x509.h>
 150 .Ve
 151 .Vb 4
 152 \& int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags);
 153 \& int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags);
 154 \& char * X509_NAME_oneline(X509_NAME *a,char *buf,int size);
 155 \& int X509_NAME_print(BIO *bp, X509_NAME *name, int obase);
 156 .Ve
 157 .SH "DESCRIPTION"
 158 .IX Header "DESCRIPTION"
 159 \&\fIX509_NAME_print_ex()\fR prints a human readable version of \fBnm\fR to \s-1BIO\s0 \fBout\fR. Each
 160 line (for multiline formats) is indented by \fBindent\fR spaces. The output format
 161 can be extensively customised by use of the \fBflags\fR parameter.
 162 .PP
 163 \&\fIX509_NAME_print_ex_fp()\fR is identical to \fIX509_NAME_print_ex()\fR except the output is
 164 written to \s-1FILE\s0 pointer \fBfp\fR.
 165 .PP
 166 \&\fIX509_NAME_oneline()\fR prints an \s-1ASCII\s0 version of \fBa\fR to \fBbuf\fR. At most \fBsize\fR
 167 bytes will be written. If \fBbuf\fR is \fB\s-1NULL\s0\fR then a buffer is dynamically allocated
 168 and returned, otherwise \fBbuf\fR is returned.
 169 .PP
 170 \&\fIX509_NAME_print()\fR prints out \fBname\fR to \fBbp\fR indenting each line by \fBobase\fR
 171 characters. Multiple lines are used if the output (including indent) exceeds
 172 80 characters.
 173 .SH "NOTES"
 174 .IX Header "NOTES"
 175 The functions \fIX509_NAME_oneline()\fR and \fIX509_NAME_print()\fR are legacy functions which
 176 produce a non standard output form, they don't handle multi character fields and
 177 have various quirks and inconsistencies. Their use is strongly discouraged in new
 178 applications.
 179 .PP
 180 Although there are a large number of possible flags for most purposes
 181 \&\fB\s-1XN_FLAG_ONELINE\s0\fR, \fB\s-1XN_FLAG_MULTILINE\s0\fR or \fB\s-1XN_FLAG_RFC2253\s0\fR will suffice.
 182 As noted on the ASN1_STRING_print_ex(3) manual page
 183 for \s-1UTF8\s0 terminals the \fB\s-1ASN1_STRFLAGS_ESC_MSB\s0\fR should be unset: so for example
 184 \&\fB\s-1XN_FLAG_ONELINE\s0 & ~ASN1_STRFLAGS_ESC_MSB\fR would be used.
 185 .PP
 186 The complete set of the flags supported by \fIX509_NAME_print_ex()\fR is listed below.
 187 .PP
 188 Several options can be ored together.
 189 .PP
 190 The options \fB\s-1XN_FLAG_SEP_COMMA_PLUS\s0\fR, \fB\s-1XN_FLAG_SEP_CPLUS_SPC\s0\fR,
 191 \&\fB\s-1XN_FLAG_SEP_SPLUS_SPC\s0\fR and \fB\s-1XN_FLAG_SEP_MULTILINE\s0\fR determine the field separators
 192 to use. Two distinct separators are used between distinct RelativeDistinguishedName
 193 components and separate values in the same \s-1RDN\s0 for a multi-valued \s-1RDN\s0. Multi-valued
 194 RDNs are currently very rare so the second separator will hardly ever be used.
 195 .PP
 196 \&\fB\s-1XN_FLAG_SEP_COMMA_PLUS\s0\fR uses comma and plus as separators. \fB\s-1XN_FLAG_SEP_CPLUS_SPC\s0\fR
 197 uses comma and plus with spaces: this is more readable that plain comma and plus.
 198 \&\fB\s-1XN_FLAG_SEP_SPLUS_SPC\s0\fR uses spaced semicolon and plus. \fB\s-1XN_FLAG_SEP_MULTILINE\s0\fR uses
 199 spaced newline and plus respectively.
 200 .PP
 201 If \fB\s-1XN_FLAG_DN_REV\s0\fR is set the whole \s-1DN\s0 is printed in reversed order.
 202 .PP
 203 The fields \fB\s-1XN_FLAG_FN_SN\s0\fR, \fB\s-1XN_FLAG_FN_LN\s0\fR, \fB\s-1XN_FLAG_FN_OID\s0\fR,
 204 \&\fB\s-1XN_FLAG_FN_NONE\s0\fR determine how a field name is displayed. It will
 205 use the short name (e.g. \s-1CN\s0) the long name (e.g. commonName) always
 206 use \s-1OID\s0 numerical form (normally OIDs are only used if the field name is not
 207 recognised) and no field name respectively.
 208 .PP
 209 If \fB\s-1XN_FLAG_SPC_EQ\s0\fR is set then spaces will be placed around the '=' character
 210 separating field names and values.
 211 .PP
 212 If \fB\s-1XN_FLAG_DUMP_UNKNOWN_FIELDS\s0\fR is set then the encoding of unknown fields is
 213 printed instead of the values.
 214 .PP
 215 If \fB\s-1XN_FLAG_FN_ALIGN\s0\fR is set then field names are padded to 20 characters: this
 216 is only of use for multiline format.
 217 .PP
 218 Additionally all the options supported by \fIASN1_STRING_print_ex()\fR can be used to
 219 control how each field value is displayed.
 220 .PP
 221 In addition a number options can be set for commonly used formats.
 222 .PP
 223 \&\fB\s-1XN_FLAG_RFC2253\s0\fR sets options which produce an output compatible with \s-1RFC2253\s0 it
 224 is equivalent to:
 225  \fB\s-1ASN1_STRFLGS_RFC2253\s0 | \s-1XN_FLAG_SEP_COMMA_PLUS\s0 | \s-1XN_FLAG_DN_REV\s0 | \s-1XN_FLAG_FN_SN\s0 | \s-1XN_FLAG_DUMP_UNKNOWN_FIELDS\s0\fR
 226 .PP
 227 \&\fB\s-1XN_FLAG_ONELINE\s0\fR is a more readable one line format it is the same as:
 228  \fB\s-1ASN1_STRFLGS_RFC2253\s0 | \s-1ASN1_STRFLGS_ESC_QUOTE\s0 | \s-1XN_FLAG_SEP_CPLUS_SPC\s0 | \s-1XN_FLAG_SPC_EQ\s0 | \s-1XN_FLAG_FN_SN\s0\fR
 229 .PP
 230 \&\fB\s-1XN_FLAG_MULTILINE\s0\fR is a multiline format is is the same as:
 231  \fB\s-1ASN1_STRFLGS_ESC_CTRL\s0 | \s-1ASN1_STRFLGS_ESC_MSB\s0 | \s-1XN_FLAG_SEP_MULTILINE\s0 | \s-1XN_FLAG_SPC_EQ\s0 | \s-1XN_FLAG_FN_LN\s0 | \s-1XN_FLAG_FN_ALIGN\s0\fR
 232 .PP
 233 \&\fB\s-1XN_FLAG_COMPAT\s0\fR uses a format identical to \fIX509_NAME_print()\fR: in fact it calls \fIX509_NAME_print()\fR internally.
 234 .SH "SEE ALSO"
 235 .IX Header "SEE ALSO"
 236 ASN1_STRING_print_ex(3)
 237 .SH "HISTORY"
 238 .IX Header "HISTORY"
 239 \&\s-1TBA\s0