1109998Smarkm=pod 2109998Smarkm 3109998Smarkm=head1 NAME 4109998Smarkm 5109998SmarkmX509_NAME_print_ex, X509_NAME_print_ex_fp, X509_NAME_print, 6109998SmarkmX509_NAME_oneline - X509_NAME printing routines. 7109998Smarkm 8109998Smarkm=head1 SYNOPSIS 9109998Smarkm 10109998Smarkm #include <openssl/x509.h> 11109998Smarkm 12109998Smarkm int X509_NAME_print_ex(BIO *out, X509_NAME *nm, int indent, unsigned long flags); 13109998Smarkm int X509_NAME_print_ex_fp(FILE *fp, X509_NAME *nm, int indent, unsigned long flags); 14109998Smarkm char * X509_NAME_oneline(X509_NAME *a,char *buf,int size); 15109998Smarkm int X509_NAME_print(BIO *bp, X509_NAME *name, int obase); 16109998Smarkm 17109998Smarkm=head1 DESCRIPTION 18109998Smarkm 19109998SmarkmX509_NAME_print_ex() prints a human readable version of B<nm> to BIO B<out>. Each 20109998Smarkmline (for multiline formats) is indented by B<indent> spaces. The output format 21109998Smarkmcan be extensively customised by use of the B<flags> parameter. 22109998Smarkm 23109998SmarkmX509_NAME_print_ex_fp() is identical to X509_NAME_print_ex() except the output is 24109998Smarkmwritten to FILE pointer B<fp>. 25109998Smarkm 26109998SmarkmX509_NAME_oneline() prints an ASCII version of B<a> to B<buf>. At most B<size> 27109998Smarkmbytes will be written. If B<buf> is B<NULL> then a buffer is dynamically allocated 28109998Smarkmand returned, otherwise B<buf> is returned. 29109998Smarkm 30109998SmarkmX509_NAME_print() prints out B<name> to B<bp> indenting each line by B<obase> 31109998Smarkmcharacters. Multiple lines are used if the output (including indent) exceeds 32109998Smarkm80 characters. 33109998Smarkm 34109998Smarkm=head1 NOTES 35109998Smarkm 36109998SmarkmThe functions X509_NAME_oneline() and X509_NAME_print() are legacy functions which 37109998Smarkmproduce a non standard output form, they don't handle multi character fields and 38109998Smarkmhave various quirks and inconsistencies. Their use is strongly discouraged in new 39109998Smarkmapplications. 40109998Smarkm 41109998SmarkmAlthough there are a large number of possible flags for most purposes 42109998SmarkmB<XN_FLAG_ONELINE>, B<XN_FLAG_MULTILINE> or B<XN_FLAG_RFC2253> will suffice. 43109998SmarkmAs noted on the L<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> manual page 44160814Ssimonfor UTF8 terminals the B<ASN1_STRFLGS_ESC_MSB> should be unset: so for example 45160814SsimonB<XN_FLAG_ONELINE & ~ASN1_STRFLGS_ESC_MSB> would be used. 46109998Smarkm 47109998SmarkmThe complete set of the flags supported by X509_NAME_print_ex() is listed below. 48109998Smarkm 49109998SmarkmSeveral options can be ored together. 50109998Smarkm 51109998SmarkmThe options B<XN_FLAG_SEP_COMMA_PLUS>, B<XN_FLAG_SEP_CPLUS_SPC>, 52109998SmarkmB<XN_FLAG_SEP_SPLUS_SPC> and B<XN_FLAG_SEP_MULTILINE> determine the field separators 53109998Smarkmto use. Two distinct separators are used between distinct RelativeDistinguishedName 54109998Smarkmcomponents and separate values in the same RDN for a multi-valued RDN. Multi-valued 55109998SmarkmRDNs are currently very rare so the second separator will hardly ever be used. 56109998Smarkm 57109998SmarkmB<XN_FLAG_SEP_COMMA_PLUS> uses comma and plus as separators. B<XN_FLAG_SEP_CPLUS_SPC> 58109998Smarkmuses comma and plus with spaces: this is more readable that plain comma and plus. 59109998SmarkmB<XN_FLAG_SEP_SPLUS_SPC> uses spaced semicolon and plus. B<XN_FLAG_SEP_MULTILINE> uses 60109998Smarkmspaced newline and plus respectively. 61109998Smarkm 62109998SmarkmIf B<XN_FLAG_DN_REV> is set the whole DN is printed in reversed order. 63109998Smarkm 64109998SmarkmThe fields B<XN_FLAG_FN_SN>, B<XN_FLAG_FN_LN>, B<XN_FLAG_FN_OID>, 65109998SmarkmB<XN_FLAG_FN_NONE> determine how a field name is displayed. It will 66109998Smarkmuse the short name (e.g. CN) the long name (e.g. commonName) always 67109998Smarkmuse OID numerical form (normally OIDs are only used if the field name is not 68109998Smarkmrecognised) and no field name respectively. 69109998Smarkm 70109998SmarkmIf B<XN_FLAG_SPC_EQ> is set then spaces will be placed around the '=' character 71109998Smarkmseparating field names and values. 72109998Smarkm 73109998SmarkmIf B<XN_FLAG_DUMP_UNKNOWN_FIELDS> is set then the encoding of unknown fields is 74109998Smarkmprinted instead of the values. 75109998Smarkm 76109998SmarkmIf B<XN_FLAG_FN_ALIGN> is set then field names are padded to 20 characters: this 77109998Smarkmis only of use for multiline format. 78109998Smarkm 79109998SmarkmAdditionally all the options supported by ASN1_STRING_print_ex() can be used to 80109998Smarkmcontrol how each field value is displayed. 81109998Smarkm 82109998SmarkmIn addition a number options can be set for commonly used formats. 83109998Smarkm 84109998SmarkmB<XN_FLAG_RFC2253> sets options which produce an output compatible with RFC2253 it 85109998Smarkmis equivalent to: 86109998Smarkm B<ASN1_STRFLGS_RFC2253 | XN_FLAG_SEP_COMMA_PLUS | XN_FLAG_DN_REV | XN_FLAG_FN_SN | XN_FLAG_DUMP_UNKNOWN_FIELDS> 87109998Smarkm 88109998Smarkm 89194206SsimonB<XN_FLAG_ONELINE> is a more readable one line format which is the same as: 90109998Smarkm B<ASN1_STRFLGS_RFC2253 | ASN1_STRFLGS_ESC_QUOTE | XN_FLAG_SEP_CPLUS_SPC | XN_FLAG_SPC_EQ | XN_FLAG_FN_SN> 91109998Smarkm 92194206SsimonB<XN_FLAG_MULTILINE> is a multiline format which is the same as: 93109998Smarkm 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> 94109998Smarkm 95109998SmarkmB<XN_FLAG_COMPAT> uses a format identical to X509_NAME_print(): in fact it calls X509_NAME_print() internally. 96109998Smarkm 97109998Smarkm=head1 SEE ALSO 98109998Smarkm 99109998SmarkmL<ASN1_STRING_print_ex(3)|ASN1_STRING_print_ex(3)> 100109998Smarkm 101109998Smarkm=head1 HISTORY 102109998Smarkm 103109998SmarkmTBA 104109998Smarkm 105109998Smarkm=cut 106