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(). 41If the argument is NULL, nothing is done. 42 43BIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets 44it back to an uninitialised state. 45 46BIO_ADDR_rawmake() takes a protocol B<family>, a byte array of 47size B<wherelen> with an address in network byte order pointed at 48by B<where> and a port number in network byte order in B<port> (except 49for the B<AF_UNIX> protocol family, where B<port> is meaningless and 50therefore ignored) and populates the given B<BIO_ADDR> with them. 51In case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected 52to be the length of the path string (not including the terminating 53NUL, such as the result of a call to strlen()). 54Read on about the addresses in L</RAW ADDRESSES> below. 55 56BIO_ADDR_family() returns the protocol family of the given 57B<BIO_ADDR>. The possible non-error results are one of the 58constants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the 59BIO_ADDR has not been initialised. 60 61BIO_ADDR_rawaddress() will write the raw address of the given 62B<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL, 63and will set B<*l> to be the amount of bytes the raw address 64takes up if B<l> is non-NULL. 65A technique to only find out the size of the address is a call 66with B<p> set to B<NULL>. The raw address will be in network byte 67order, most significant byte first. 68In case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the 69path string (not including the terminating NUL, such as the result of 70a call to strlen()). 71Read on about the addresses in L</RAW ADDRESSES> below. 72 73BIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>. 74The raw port will be in network byte order. 75 76BIO_ADDR_hostname_string() returns a character string with the 77hostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string 78will contain the numerical form of the address. This only works for 79B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 80returned string has been allocated on the heap and must be freed 81with OPENSSL_free(). 82 83BIO_ADDR_service_string() returns a character string with the 84service name of the port of the given B<BIO_ADDR>. If B<numeric> 85is 1, the string will contain the port number. This only works 86for B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 87returned string has been allocated on the heap and must be freed 88with OPENSSL_free(). 89 90BIO_ADDR_path_string() returns a character string with the path 91of the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the 92protocol family AF_UNIX. The returned string has been allocated 93on the heap and must be freed with OPENSSL_free(). 94 95=head1 RAW ADDRESSES 96 97Both BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a 98network byte order address of a specific site. Internally, those are 99treated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct 100in6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all 101depending on the protocol family the address is for. 102 103=head1 RETURN VALUES 104 105The string producing functions BIO_ADDR_hostname_string(), 106BIO_ADDR_service_string() and BIO_ADDR_path_string() will 107return B<NULL> on error and leave an error indication on the 108OpenSSL error stack. 109 110All other functions described here return 0 or B<NULL> when the 111information they should return isn't available. 112 113=head1 SEE ALSO 114 115L<BIO_connect(3)>, L<BIO_s_connect(3)> 116 117=head1 COPYRIGHT 118 119Copyright 2016-2024 The OpenSSL Project Authors. All Rights Reserved. 120 121Licensed under the Apache License 2.0 (the "License"). You may not use 122this file except in compliance with the License. You can obtain a copy 123in the file LICENSE in the source distribution or at 124L<https://www.openssl.org/source/license.html>. 125 126=cut 127