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