=pod
+=head1 NAME
+
X509_NAME_get_index_by_NID, X509_NAME_get_index_by_OBJ, X509_NAME_get_entry,
X509_NAME_entry_count, X509_NAME_get_text_by_NID, X509_NAME_get_text_by_OBJ -
X509_NAME lookup and enumeration functions
-=head1 NAME
-
=head1 SYNOPSIS
-int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
-int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
+ #include <openssl/x509.h>
-int X509_NAME_entry_count(X509_NAME *name);
-X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
+ int X509_NAME_get_index_by_NID(X509_NAME *name,int nid,int lastpos);
+ int X509_NAME_get_index_by_OBJ(X509_NAME *name,ASN1_OBJECT *obj, int lastpos);
-int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
-int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
+ int X509_NAME_entry_count(X509_NAME *name);
+ X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
+
+ int X509_NAME_get_text_by_NID(X509_NAME *name, int nid, char *buf,int len);
+ int X509_NAME_get_text_by_OBJ(X509_NAME *name, ASN1_OBJECT *obj, char *buf,int len);
=head1 DESCRIPTION
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ() retrieve
the next index matching B<nid> or B<obj> after B<lastpos>. B<lastpos>
should initially be set to -1. If there are no more entries -1 is returned.
+If B<nid> is invalid (doesn't correspond to a valid OID) then -2 is returned.
X509_NAME_entry_count() returns the total number of entries in B<name>.
X509_NAME_get_entry() on any matching indices and then the
various B<X509_NAME_ENTRY> utility functions on the result.
+The list of all relevant B<NID_*> and B<OBJ_* codes> can be found in
+the source code header files E<lt>openssl/obj_mac.hE<gt> and/or
+E<lt>openssl/objects.hE<gt>.
+
+Applications which could pass invalid NIDs to X509_NAME_get_index_by_NID()
+should check for the return value of -2. Alternatively the NID validity
+can be determined first by checking OBJ_nid2obj(nid) is not NULL.
+
=head1 EXAMPLES
Process all entries:
X509_NAME_get_index_by_NID() and X509_NAME_get_index_by_OBJ()
return the index of the next matching entry or -1 if not found.
+X509_NAME_get_index_by_NID() can also return -2 if the supplied
+NID is invalid.
X509_NAME_entry_count() returns the total number of entries.