summaryrefslogtreecommitdiff
path: root/src/lib/libcrypto/doc/X509_NAME_print_ex.pod
diff options
context:
space:
mode:
Diffstat (limited to 'src/lib/libcrypto/doc/X509_NAME_print_ex.pod')
-rw-r--r--src/lib/libcrypto/doc/X509_NAME_print_ex.pod103
1 files changed, 0 insertions, 103 deletions
diff --git a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod b/src/lib/libcrypto/doc/X509_NAME_print_ex.pod
deleted file mode 100644
index 5cdf636c16..0000000000
--- a/src/lib/libcrypto/doc/X509_NAME_print_ex.pod
+++ /dev/null
@@ -1,103 +0,0 @@
1=pod
2
3=head1 NAME
4
5X509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print,
6X509_NAME_oneline - X509_NAME printing routines.
7
8=head1 SYNOPSIS
9
10 #include <openssl/x509.h>
11
12 int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags);
13 int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags);
14 char * X509_NAME_oneline(X509_NAME *a,char *buf,int size);
15 int X509_NAME_print(BIO *bp, X509_NAME *name, int obase);
16
17=head1 DESCRIPTION
18
19X509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>.
20Each line (for multiline formats) is indented by B<indent> spaces. The output
21format can be extensively customised by use of the B<flags> parameter.
22
23X509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output
24is written to FILE pointer B<fp>.
25
26X509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size>
27bytes will be written. If B<buf> is B<NULL> then a buffer is dynamically
28allocated and returned, otherwise B<buf> is returned.
29
30X509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase>
31characters. Multiple lines are used if the output (including indent) exceeds
3280 characters.
33
34=head1 NOTES
35
36The functions X509_NAME_oneline() and X509_NAME_print() are legacy functions
37which produce a non standard output form, they don't handle multi character
38fields and have various quirks and inconsistencies. Their use is strongly
39discouraged in new applications.
40
41Although there are a large number of possible flags for most purposes
42B<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice.
43As noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page
44for UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example
45B<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used.
46
47The complete set of the flags supported by X509_NAME_print_ex() is listed below.
48
49Several options can be ored together.
50
51The options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>,
52B<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field
53separators to use. Two distinct separators are used between distinct
54RelativeDistinguishedName components and separate values in the same RDN for a
55multi-valued RDN. Multi-valued RDNs are currently very rare so the second
56separator will hardly ever be used.
57
58B<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators.
59B<XN_FLAG_SEP_CPLUS_SPC> uses comma and plus with spaces: this is more readable
60that plain comma and plus. B<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and
61plus. B<XN_FLAG_SEP_MULTILINE> uses spaced newline and plus respectively.
62
63If B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order.
64
65The fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>,
66B<XN_FLAG_FN_NONE> determine how a field name is displayed. It will
67use the short name (e.g. CN) the long name (e.g. commonName) always
68use OID numerical form (normally OIDs are only used if the field name is not
69recognised) and no field name respectively.
70
71If B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character
72separating field names and values.
73
74If B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is
75printed instead of the values.
76
77If B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this
78is only of use for multiline format.
79
80Additionally all the options supported by ASN1_STRING_print_ex() can be used to
81control how each field value is displayed.
82
83In addition a number options can be set for commonly used formats.
84
85B<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it
86is equivalent to:
87 B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS>
88
89
90B<XN_FLAG_ONELINE> is a more readable one line format which is the same as:
91 B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN>
92
93B<XN_FLAG_MULTILINE> is a multiline format which is the same as:
94 B<ASN1_STRFLGS_ESC_CTRL | ASN1_STRFLGS_ESC_MSB | XN_FLAG_SEP_MULTILINE | XN_FLAG_SPC_EQ | XN_FLAG_FN_LN | XN_FLAG_FN_ALIGN>
95
96B<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it
97calls X509_NAME_print() internally.
98
99=head1 SEE ALSO
100
101L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)>
102
103=cut