Refer to OPENSSLDIR rather than "the OpenSSL install directory"

[openssl.git] / doc / crypto / X509_NAME_get_index_by_NID.pod

diff --git a/doc/crypto/X509_NAME_get_index_by_NID.pod b/doc/crypto/X509_NAME_get_index_by_NID.pod
index 84fc18027a7f2829958e2be2b8efcc4c99dcc20e..042da246971ac723641a1ada4a63e929c232713b 100644 (file)
--- a/doc/crypto/X509_NAME_get_index_by_NID.pod
+++ b/doc/crypto/X509_NAME_get_index_by_NID.pod
@@ -10,14 +10,14 @@ X509_NAME lookup and enumeration functions
 
  #include <openssl/x509.h>
 
- 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_index_by_NID(X509_NAME *name, int nid, int lastpos);
+ int X509_NAME_get_index_by_OBJ(X509_NAME *name, const ASN1_OBJECT *obj, int lastpos);
 
- int X509_NAME_entry_count(X509_NAME *name);
- X509_NAME_ENTRY *X509_NAME_get_entry(X509_NAME *name, int loc);
+ int X509_NAME_entry_count(const X509_NAME *name);
+ X509_NAME_ENTRY *X509_NAME_get_entry(const 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);
+ 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, const ASN1_OBJECT *obj, char *buf, int len);
 
 =head1 DESCRIPTION
 
@@ -29,6 +29,7 @@ and issuer names.
 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>.
 
@@ -43,7 +44,7 @@ B<obj>, if no such entry exists -1 is returned. At most B<len> bytes
 will be written and the text written to B<buf> will be null
 terminated. The length of the output string written is returned
 excluding the terminating null. If B<buf> is <NULL> then the amount
-of space needed in B<buf> (excluding the final null) is returned. 
+of space needed in B<buf> (excluding the final null) is returned.
 
 =head1 NOTES
 
@@ -63,6 +64,10 @@ 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:
@@ -71,10 +76,10 @@ Process all entries:
  X509_NAME_ENTRY *e;
 
  for (i = 0; i < X509_NAME_entry_count(nm); i++)
-       {
-       e = X509_NAME_get_entry(nm, i);
-       /* Do something with e */
-       }
+        {
+        e = X509_NAME_get_entry(nm, i);
+        /* Do something with e */
+        }
 
 Process all commonName entries:
 
@@ -83,18 +88,20 @@ Process all commonName entries:
 
  loc = -1;
  for (;;)
-       {
-       lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
-       if (lastpos == -1)
-               break;
-       e = X509_NAME_get_entry(nm, lastpos);
-       /* Do something with e */
-       }
+        {
+        lastpos = X509_NAME_get_index_by_NID(nm, NID_commonName, lastpos);
+        if (lastpos == -1)
+                break;
+        e = X509_NAME_get_entry(nm, lastpos);
+        /* Do something with e */
+        }
 
 =head1 RETURN VALUES
 
 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.
 
@@ -103,10 +110,15 @@ requested entry or B<NULL> if the index is invalid.
 
 =head1 SEE ALSO
 
-L<ERR_get_error(3)|ERR_get_error(3)>, L<d2i_X509_NAME(3)|d2i_X509_NAME(3)>
+L<ERR_get_error(3)>, L<d2i_X509_NAME(3)>
+
+=head1 COPYRIGHT
 
-=head1 HISTORY
+Copyright 2002-2016 The OpenSSL Project Authors. All Rights Reserved.
 
-TBA
+Licensed under the OpenSSL license (the "License").  You may not use
+this file except in compliance with the License.  You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
 
 =cut