105901b04Schristos=pod 205901b04Schristos 305901b04Schristos=head1 NAME 405901b04Schristos 505901b04SchristosBIO_ADDR, BIO_ADDR_new, BIO_ADDR_clear, BIO_ADDR_free, BIO_ADDR_rawmake, 605901b04SchristosBIO_ADDR_family, BIO_ADDR_rawaddress, BIO_ADDR_rawport, 705901b04SchristosBIO_ADDR_hostname_string, BIO_ADDR_service_string, 805901b04SchristosBIO_ADDR_path_string - BIO_ADDR routines 905901b04Schristos 1005901b04Schristos=head1 SYNOPSIS 1105901b04Schristos 1205901b04Schristos #include <sys/types.h> 1305901b04Schristos #include <openssl/bio.h> 1405901b04Schristos 1505901b04Schristos typedef union bio_addr_st BIO_ADDR; 1605901b04Schristos 1705901b04Schristos BIO_ADDR *BIO_ADDR_new(void); 1805901b04Schristos void BIO_ADDR_free(BIO_ADDR *); 1905901b04Schristos void BIO_ADDR_clear(BIO_ADDR *ap); 2005901b04Schristos int BIO_ADDR_rawmake(BIO_ADDR *ap, int family, 2105901b04Schristos const void *where, size_t wherelen, unsigned short port); 2205901b04Schristos int BIO_ADDR_family(const BIO_ADDR *ap); 2305901b04Schristos int BIO_ADDR_rawaddress(const BIO_ADDR *ap, void *p, size_t *l); 2405901b04Schristos unsigned short BIO_ADDR_rawport(const BIO_ADDR *ap); 2505901b04Schristos char *BIO_ADDR_hostname_string(const BIO_ADDR *ap, int numeric); 2605901b04Schristos char *BIO_ADDR_service_string(const BIO_ADDR *ap, int numeric); 2705901b04Schristos char *BIO_ADDR_path_string(const BIO_ADDR *ap); 2805901b04Schristos 2905901b04Schristos=head1 DESCRIPTION 3005901b04Schristos 3105901b04SchristosThe B<BIO_ADDR> type is a wrapper around all types of socket 3205901b04Schristosaddresses that OpenSSL deals with, currently transparently 3305901b04Schristossupporting AF_INET, AF_INET6 and AF_UNIX according to what's 3405901b04Schristosavailable on the platform at hand. 3505901b04Schristos 3605901b04SchristosBIO_ADDR_new() creates a new unfilled B<BIO_ADDR>, to be used 3705901b04Schristoswith routines that will fill it with information, such as 3805901b04SchristosBIO_accept_ex(). 3905901b04Schristos 4005901b04SchristosBIO_ADDR_free() frees a B<BIO_ADDR> created with BIO_ADDR_new(). 4105901b04Schristos 4205901b04SchristosBIO_ADDR_clear() clears any data held within the provided B<BIO_ADDR> and sets 4305901b04Schristosit back to an uninitialised state. 4405901b04Schristos 4579323285SchristosBIO_ADDR_rawmake() takes a protocol B<family>, a byte array of 4605901b04Schristossize B<wherelen> with an address in network byte order pointed at 4705901b04Schristosby B<where> and a port number in network byte order in B<port> (except 4805901b04Schristosfor the B<AF_UNIX> protocol family, where B<port> is meaningless and 4905901b04Schristostherefore ignored) and populates the given B<BIO_ADDR> with them. 5005901b04SchristosIn case this creates a B<AF_UNIX> B<BIO_ADDR>, B<wherelen> is expected 5105901b04Schristosto be the length of the path string (not including the terminating 5205901b04SchristosNUL, such as the result of a call to strlen()). 53*66bae5e7SchristosRead on about the addresses in L</RAW ADDRESSES> below. 5405901b04Schristos 5505901b04SchristosBIO_ADDR_family() returns the protocol family of the given 5605901b04SchristosB<BIO_ADDR>. The possible non-error results are one of the 5705901b04Schristosconstants AF_INET, AF_INET6 and AF_UNIX. It will also return AF_UNSPEC if the 5805901b04SchristosBIO_ADDR has not been initialised. 5905901b04Schristos 6005901b04SchristosBIO_ADDR_rawaddress() will write the raw address of the given 6105901b04SchristosB<BIO_ADDR> in the area pointed at by B<p> if B<p> is non-NULL, 6205901b04Schristosand will set B<*l> to be the amount of bytes the raw address 6305901b04Schristostakes up if B<l> is non-NULL. 6405901b04SchristosA technique to only find out the size of the address is a call 6505901b04Schristoswith B<p> set to B<NULL>. The raw address will be in network byte 6605901b04Schristosorder, most significant byte first. 6705901b04SchristosIn case this is a B<AF_UNIX> B<BIO_ADDR>, B<l> gets the length of the 6805901b04Schristospath string (not including the terminating NUL, such as the result of 6905901b04Schristosa call to strlen()). 70*66bae5e7SchristosRead on about the addresses in L</RAW ADDRESSES> below. 7105901b04Schristos 7205901b04SchristosBIO_ADDR_rawport() returns the raw port of the given B<BIO_ADDR>. 7305901b04SchristosThe raw port will be in network byte order. 7405901b04Schristos 7505901b04SchristosBIO_ADDR_hostname_string() returns a character string with the 7605901b04Schristoshostname of the given B<BIO_ADDR>. If B<numeric> is 1, the string 7705901b04Schristoswill contain the numerical form of the address. This only works for 7805901b04SchristosB<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 7905901b04Schristosreturned string has been allocated on the heap and must be freed 8005901b04Schristoswith OPENSSL_free(). 8105901b04Schristos 8205901b04SchristosBIO_ADDR_service_string() returns a character string with the 8305901b04Schristosservice name of the port of the given B<BIO_ADDR>. If B<numeric> 8405901b04Schristosis 1, the string will contain the port number. This only works 8505901b04Schristosfor B<BIO_ADDR> of the protocol families AF_INET and AF_INET6. The 8605901b04Schristosreturned string has been allocated on the heap and must be freed 8705901b04Schristoswith OPENSSL_free(). 8805901b04Schristos 8905901b04SchristosBIO_ADDR_path_string() returns a character string with the path 9005901b04Schristosof the given B<BIO_ADDR>. This only works for B<BIO_ADDR> of the 9105901b04Schristosprotocol family AF_UNIX. The returned string has been allocated 9205901b04Schristoson the heap and must be freed with OPENSSL_free(). 9305901b04Schristos 9405901b04Schristos=head1 RAW ADDRESSES 9505901b04Schristos 9605901b04SchristosBoth BIO_ADDR_rawmake() and BIO_ADDR_rawaddress() take a pointer to a 9705901b04Schristosnetwork byte order address of a specific site. Internally, those are 9805901b04Schristostreated as a pointer to B<struct in_addr> (for B<AF_INET>), B<struct 9905901b04Schristosin6_addr> (for B<AF_INET6>) or B<char *> (for B<AF_UNIX>), all 10005901b04Schristosdepending on the protocol family the address is for. 10105901b04Schristos 10205901b04Schristos=head1 RETURN VALUES 10305901b04Schristos 10405901b04SchristosThe string producing functions BIO_ADDR_hostname_string(), 10505901b04SchristosBIO_ADDR_service_string() and BIO_ADDR_path_string() will 10605901b04Schristosreturn B<NULL> on error and leave an error indication on the 10705901b04SchristosOpenSSL error stack. 10805901b04Schristos 10905901b04SchristosAll other functions described here return 0 or B<NULL> when the 11005901b04Schristosinformation they should return isn't available. 11105901b04Schristos 11205901b04Schristos=head1 SEE ALSO 11305901b04Schristos 11405901b04SchristosL<BIO_connect(3)>, L<BIO_s_connect(3)> 11505901b04Schristos 11605901b04Schristos=head1 COPYRIGHT 11705901b04Schristos 11879323285SchristosCopyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved. 11905901b04Schristos 120*66bae5e7SchristosLicensed under the Apache License 2.0 (the "License"). You may not use 12105901b04Schristosthis file except in compliance with the License. You can obtain a copy 12205901b04Schristosin the file LICENSE in the source distribution or at 12305901b04SchristosL<https://www.openssl.org/source/license.html>. 12405901b04Schristos 12505901b04Schristos=cut 126