1=pod 2 3=head1 NAME 4 5BIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, 6BIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, 7BIO_ADDR_hostname_string, BIO_ADDR_service_string, 8BIO_ADDR_path_string - BIO_ADDR routines 9 10=head1 SYNOPSIS 11 12 #include <sys/types.h> 13 #include <openssl/bio.h> 14 15 typedef union bio_addr_st BIO_ADDR; 16 17 BIO_ADDR *BIO_ADDR_new(void); 18 void BIO_ADDR_free(BIO_ADDR *); 19 void BIO_ADDR_clear(BIO_ADDR *ap); 20 int BIO_ADDR_rawmake(BIO_ADDR *ap, int family, 21 const void *where, size_t wherelen, unsigned short port); 22 int BIO_ADDR_family(const BIO_ADDR *ap); 23 int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l); 24 unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap); 25 char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric); 26 char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric); 27 char *BIO_ADDR_path_string(const BIO_ADDR *ap); 28 29=head1 DESCRIPTION 30 31The B<BIO_ADDR> type is a wrapper around all types of socket 32addresses that OpenSSL deals with, currently transparently 33supporting AF_INET, AF_INET6 and AF_UNIX according to what's 34available on the platform at hand. 35 36BIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used 37with routines that will fill it with information, such as 38BIO_accept_ex(). 39 40BIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new(). 41 42BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets 43it back to an uninitialised state. 44 45BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of 46size B<wherelen> with an address in network byte order pointed at 47by B<where> and a port number in network byte order in B<port> (except 48for the B<AF_UNIX> protocol family, where B<port> is meaningless and 49therefore ignored) and populates the given B<BIO_ADDR> with them. 50In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected 51to be the length of the path string (not including the terminating 52NUL, such as the result of a call to strlen()). 53I<Read on about the addresses in L</RAW ADDRESSES> below>. 54 55BIO_ADDR_family() returns the protocol family of the given 56B<BIO_ADDR>. The possible non-error results are one of the 57constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the 58BIO_ADDR has not been initialised. 59 60BIO_ADDR_rawaddress() will write the raw address of the given 61B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL, 62and will set B<*l> to be the amount of bytes the raw address 63takes up if B<l> is non-NULL. 64A technique to only find out the size of the address is a call 65with B<p> set to B<NULL>. The raw address will be in network byte 66order, most significant byte first. 67In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the 68path string (not including the terminating NUL, such as the result of 69a call to strlen()). 70I<Read on about the addresses in L</RAW ADDRESSES> below>. 71 72BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>. 73The raw port will be in network byte order. 74 75BIO_ADDR_hostname_string() returns a character string with the 76hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string 77will contain the numerical form of the address. This only works for 78B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 79returned string has been allocated on the heap and must be freed 80with OPENSSL_free(). 81 82BIO_ADDR_service_string() returns a character string with the 83service name of the port of the given B<BIO_ADDR>. If B<numeric> 84is 1, the string will contain the port number. This only works 85for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 86returned string has been allocated on the heap and must be freed 87with OPENSSL_free(). 88 89BIO_ADDR_path_string() returns a character string with the path 90of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the 91protocol family AF_UNIX. The returned string has been allocated 92on the heap and must be freed with OPENSSL_free(). 93 94=head1 RAW ADDRESSES 95 96Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a 97network byte order address of a specific site. Internally, those are 98treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct 99in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all 100depending on the protocol family the address is for. 101 102=head1 RETURN VALUES 103 104The string producing functions BIO_ADDR_hostname_string(), 105BIO_ADDR_service_string() and BIO_ADDR_path_string() will 106return B<NULL> on error and leave an error indication on the 107OpenSSL error stack. 108 109All other functions described here return 0 or B<NULL> when the 110information they should return isn't available. 111 112=head1 SEE ALSO 113 114L<BIO_connect(3)>, L<BIO_s_connect(3)> 115 116=head1 COPYRIGHT 117 118Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 119 120Licensed under the OpenSSL license (the "License"). You may not use 121this file except in compliance with the License. You can obtain a copy 122in the file LICENSE in the source distribution or at 123L<https://www.openssl.org/source/license.html>. 124 125=cut 126