Commit e8291428 authored by Matt Caswell's avatar Matt Caswell
Browse files

Document BIO_lookup_ex() 



We also change the enum type to an int.

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

crypto/bio/b_addr.c

+1 −2
Original line number Diff line number Diff line
@@ -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 */

doc/man3/BIO_ADDRINFO.pod

+22 −8
Original line number Diff line number Diff line
@@ -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

include/openssl/bio.h

+2 −2
Original line number Diff line number Diff line
@@ -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);