Fix doc-nits issue

[openssl.git] / doc / man3 / BIO_ADDRINFO.pod

diff --git a/doc/man3/BIO_ADDRINFO.pod b/doc/man3/BIO_ADDRINFO.pod
index 7811da46a570da633a2fa09ec464364609f2d442..8ca6454abbcb2a15ef00a10d537803e362404ea6 100644 (file)
--- a/doc/man3/BIO_ADDRINFO.pod
+++ b/doc/man3/BIO_ADDRINFO.pod
@@ -6,6 +6,7 @@ BIO_lookup_type,
 BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
 BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
 BIO_ADDRINFO_address,
 BIO_ADDRINFO, BIO_ADDRINFO_next, BIO_ADDRINFO_free,
 BIO_ADDRINFO_family, BIO_ADDRINFO_socktype, BIO_ADDRINFO_protocol,
 BIO_ADDRINFO_address,

+BIO_lookup_ex,

 BIO_lookup
 - BIO_ADDRINFO type and routines
 
 BIO_lookup
 - BIO_ADDRINFO type and routines
 


@@ -19,6 +20,9 @@ BIO_lookup
  enum BIO_lookup_type {
      BIO_LOOKUP_CLIENT, BIO_LOOKUP_SERVER
  };
  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);
  int BIO_lookup(const char *node, const char *service,
                 enum BIO_lookup_type lookup_type,
                 int family, int socktype, BIO_ADDRINFO **res);


@@ -38,18 +42,24 @@ types provided on your platform.
 B<BIO_ADDRINFO> normally forms a chain of several that can be
 picked at one by one.
 
 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
 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
 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.
 chain.

-For the family B<AF_UNIX>, BIO_lookup() will ignore the B<service>
+
+For the family B<AF_UNIX>, BIO_lookup_ex() will ignore the B<service>

 parameter and expects the B<node> parameter to hold the path to the
 socket file.
 
 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.
 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 +83,28 @@ with the given one.
 
 =head1 RETURN VALUES
 
 
 =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.
 
 
 All other functions described here return 0 or B<NULL> when the
 information they should return isn't available.
 

+=head1 NOTES
+
+The BIO_lookup_ex() implementation uses the platform provided getaddrinfo()
+function. On Linux it is known that specifying 0 for the protocol will not
+return any SCTP based addresses when calling getaddrinfo(). Therefore if an SCTP
+address is required then the B<protocol> parameter to BIO_lookup_ex() should be
+explicitly set to IPPROTO_SCTP. The same may be true on other platforms.
+
+=head1 HISTORY
+
+The BIO_lookup_ex() function was added in OpenSSL 1.1.1.
+

 =head1 COPYRIGHT
 
 =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
 
 Licensed under the OpenSSL license (the "License").  You may not use
 this file except in compliance with the License.  You can obtain a copy