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