Document BIO_lookup_ex()

We also change the enum type to an int.

Reviewed-by: Richard Levitte <levitte@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/3286)

3 files changed, 25 insertions, 12 deletions

diff --git a/crypto/bio/b_addr.c b/crypto/bio/b_addr.c
index 141f1a9ee9..82c220a2f2 100644
--- a/crypto/bio/b_addr.c
+++ b/crypto/bio/b_addr.c
@@ -638,8 +638,7 @@ int BIO_lookup(const char *host, const char *service,
  *
  * The return value is 1 on success or 0 in case of error.
  */
-int BIO_lookup_ex(const char *host, const char *service,
-                  enum BIO_lookup_type lookup_type,
+int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
                   int family, int socktype, int protocol, BIO_ADDRINFO **res)
 {
     int ret = 0;                 /* Assume failure */
diff --git a/doc/man3/BIO_ADDRINFO.pod b/doc/man3/BIO_ADDRINFO.pod
index 7811da46a5..45e6e05761 100644
--- a/doc/man3/BIO_ADDRINFO.pod
+++ b/doc/man3/BIO_ADDRINFO.pod
@@ -19,6 +19,9 @@ BIO_lookup
  enum BIO_lookup_type {
      BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
  };
+
+ int BIO_lookup_ex(const char *host, const char *service, int lookup_type,
+                   int family, int socktype, int protocol, BIO_ADDRINFO **res);
  int BIO_lookup(const char *node, const char *service,
                 enum BIO_lookup_type lookup_type,
                 int family, int socktype, BIO_ADDRINFO **res);
@@ -38,18 +41,24 @@ types provided on your platform.
 B<BIO_ADDRINFO> normally forms a chain of several that can be
 picked at one by one.
 
-BIO_lookup() looks up a specified B<host> and B<service>, and
+BIO_lookup_ex() looks up a specified B<host> and B<service>, and
 uses B<lookup_type> to determine what the default address should
-be if B<host> is B<NULL>.  B<family>, B<socktype> are used to
-determine what protocol family and protocol should be used for
+be if B<host> is B<NULL>. B<family>, B<socktype> and B<protocol> are used to
+determine what protocol family, socket type and protocol should be used for
 the lookup.  B<family> can be any of AF_INET, AF_INET6, AF_UNIX and
-AF_UNSPEC, and B<socktype> can be SOCK_STREAM or SOCK_DGRAM.
-B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
+AF_UNSPEC. B<socktype> can be SOCK_STREAM, SOCK_DGRAM or 0. Specifying 0
+indicates that any type can be used. B<protocol> specifies a protocol such as
+IPPROTO_TCP, IPPROTO_UDP or IPPORTO_SCTP. If set to 0 than any protocol can be
+used. B<res> points at a pointer to hold the start of a B<BIO_ADDRINFO>
 chain.
+
 For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
 parameter and expects the B<node> parameter to hold the path to the
 socket file.
 
+BIO_lookup() does the same as BIO_lookup_ex() but does not provide the ability
+to select based on the protocol (any protocol may be returned).
+
 BIO_ADDRINFO_family() returns the family of the given
 B<BIO_ADDRINFO>.  The result will be one of the constants
 AF_INET, AF_INET6 and AF_UNIX.
@@ -73,15 +82,20 @@ with the given one.
 
 =head1 RETURN VALUES
 
-BIO_lookup() returns 1 on success and 0 when an error occurred, and
-will leave an error indication on the OpenSSL error stack in that case.
+BIO_lookup_ex() and BIO_lookup() return 1 on success and 0 when an error
+occurred, and will leave an error indication on the OpenSSL error stack in that
+case.
 
 All other functions described here return 0 or B<NULL> when the
 information they should return isn't available.
 
+=head1 HISTORY
+
+The BIO_lookup_ex() function was added in OpenSSL 1.1.1.
+
 =head1 COPYRIGHT
 
-Copyright 2016 The OpenSSL Project Authors. All Rights Reserved.
+Copyright 2016-2017 The OpenSSL Project Authors. All Rights Reserved.
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy
diff --git a/include/openssl/bio.h b/include/openssl/bio.h
index dea28c1cc1..b1276a542d 100644
--- a/include/openssl/bio.h
+++ b/include/openssl/bio.h
@@ -668,8 +668,8 @@ int BIO_lookup(const char *host, const char *service,
                enum BIO_lookup_type lookup_type,
                int family, int socktype, BIO_ADDRINFO **res);
 int BIO_lookup_ex(const char *host, const char *service,
-                  enum BIO_lookup_type lookup_type,
-                  int family, int socktype, int protocol, BIO_ADDRINFO **res);
+                  int lookup_type, int family, int socktype, int protocol,
+                  BIO_ADDRINFO **res);
 int BIO_sock_error(int sock);
 int BIO_socket_ioctl(int fd, long type, void *arg);
 int BIO_socket_nbio(int fd, int mode);