]>
Commit | Line | Data |
---|---|---|
bace2124 DSH |
1 | =pod |
2 | ||
3 | =head1 NAME | |
4 | ||
75f036c6 DDO |
5 | BIO_s_connect, BIO_new_connect, |
6 | BIO_set_conn_hostname, BIO_set_conn_port, | |
7 | BIO_set_conn_address, BIO_set_conn_ip_family, | |
2cb8445a | 8 | BIO_get_conn_hostname, BIO_get_conn_port, |
75f036c6 | 9 | BIO_get_conn_address, BIO_get_conn_ip_family, |
8eec1389 | 10 | BIO_set_nbio, BIO_do_connect - connect BIO |
bace2124 DSH |
11 | |
12 | =head1 SYNOPSIS | |
13 | ||
14 | #include <openssl/bio.h> | |
15 | ||
75f036c6 | 16 | const BIO_METHOD *BIO_s_connect(void); |
bace2124 | 17 | |
bbdc9c98 | 18 | BIO *BIO_new_connect(char *name); |
bace2124 | 19 | |
bbdc9c98 UM |
20 | long BIO_set_conn_hostname(BIO *b, char *name); |
21 | long BIO_set_conn_port(BIO *b, char *port); | |
417be660 | 22 | long BIO_set_conn_address(BIO *b, BIO_ADDR *addr); |
2cb8445a | 23 | long BIO_set_conn_ip_family(BIO *b, long family); |
417be660 RL |
24 | const char *BIO_get_conn_hostname(BIO *b); |
25 | const char *BIO_get_conn_port(BIO *b); | |
26 | const BIO_ADDR *BIO_get_conn_address(BIO *b); | |
2cb8445a | 27 | const long BIO_get_conn_ip_family(BIO *b); |
bace2124 | 28 | |
bbdc9c98 UM |
29 | long BIO_set_nbio(BIO *b, long n); |
30 | ||
31 | int BIO_do_connect(BIO *b); | |
bace2124 DSH |
32 | |
33 | =head1 DESCRIPTION | |
34 | ||
35 | BIO_s_connect() returns the connect BIO method. This is a wrapper | |
36 | round the platform's TCP/IP socket connection routines. | |
37 | ||
bbdc9c98 | 38 | Using connect BIOs, TCP/IP connections can be made and data |
bace2124 DSH |
39 | transferred using only BIO routines. In this way any platform |
40 | specific operations are hidden by the BIO abstraction. | |
41 | ||
42 | Read and write operations on a connect BIO will perform I/O | |
43 | on the underlying connection. If no connection is established | |
44 | and the port and hostname (see below) is set up properly then | |
45 | a connection is established first. | |
46 | ||
47 | Connect BIOs support BIO_puts() but not BIO_gets(). | |
48 | ||
49 | If the close flag is set on a connect BIO then any active | |
50 | connection is shutdown and the socket closed when the BIO | |
51 | is freed. | |
52 | ||
53 | Calling BIO_reset() on a connect BIO will close any active | |
54 | connection and reset the BIO into a state where it can connect | |
55 | to the same host again. | |
56 | ||
75f036c6 DDO |
57 | BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into |
58 | a single call: that is it creates a new connect BIO with hostname B<name>. | |
bace2124 | 59 | |
bbdc9c98 | 60 | BIO_set_conn_hostname() uses the string B<name> to set the hostname. |
b9b6a7e5 | 61 | The hostname can be an IP address; if the address is an IPv6 one, it |
75f036c6 DDO |
62 | must be enclosed with brackets C<[> and C<]>. |
63 | The hostname can also include the port in the form hostname:port; | |
64 | see L<BIO_parse_hostserv(3)> and BIO_set_conn_port() for details. | |
bace2124 DSH |
65 | |
66 | BIO_set_conn_port() sets the port to B<port>. B<port> can be the | |
75f036c6 DDO |
67 | numerical form or a service string such as "http", which |
68 | will be mapped to a port number using the system function getservbyname(). | |
bace2124 | 69 | |
417be660 RL |
70 | BIO_set_conn_address() sets the address and port information using |
71 | a BIO_ADDR(3ssl). | |
bace2124 | 72 | |
2cb8445a VC |
73 | BIO_set_conn_ip_family() sets the IP family. |
74 | ||
bace2124 | 75 | BIO_get_conn_hostname() returns the hostname of the connect BIO or |
1e4e5492 | 76 | NULL if the BIO is initialized but no hostname is set. |
bace2124 DSH |
77 | This return value is an internal pointer which should not be modified. |
78 | ||
79 | BIO_get_conn_port() returns the port as a string. | |
417be660 | 80 | This return value is an internal pointer which should not be modified. |
bace2124 | 81 | |
417be660 RL |
82 | BIO_get_conn_address() returns the address information as a BIO_ADDR. |
83 | This return value is an internal pointer which should not be modified. | |
bace2124 | 84 | |
2cb8445a VC |
85 | BIO_get_conn_ip_family() returns the IP family of the connect BIO. |
86 | ||
bace2124 DSH |
87 | BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is |
88 | zero then blocking I/O is set. If B<n> is 1 then non blocking I/O | |
2273d6b6 | 89 | is set. Blocking I/O is the default. The call to BIO_set_nbio() |
1bc74519 | 90 | should be made before the connection is established because |
2273d6b6 | 91 | non blocking I/O is set during the connect process. |
bace2124 | 92 | |
59131529 DDO |
93 | BIO_do_connect() attempts to connect the supplied BIO. |
94 | This performs an SSL/TLS handshake as far as supported by the BIO. | |
95 | For non-SSL BIOs the connection is done typically at TCP level. | |
96 | If domain name resolution yields multiple IP addresses all of them are tried | |
97 | after connect() failures. | |
98 | The function returns 1 if the connection was established successfully. | |
99 | A zero or negative value is returned if the connection could not be established. | |
100 | The call BIO_should_retry() should be used for non blocking connect BIOs | |
bace2124 | 101 | to determine if the call should be retried. |
59131529 | 102 | If a connection has already been established this call has no effect. |
bace2124 | 103 | |
bace2124 DSH |
104 | =head1 NOTES |
105 | ||
106 | If blocking I/O is set then a non positive return value from any | |
107 | I/O call is caused by an error condition, although a zero return | |
108 | will normally mean that the connection was closed. | |
109 | ||
9c0586d5 | 110 | If the port name is supplied as part of the hostname then this will |
2273d6b6 DSH |
111 | override any value set with BIO_set_conn_port(). This may be undesirable |
112 | if the application does not wish to allow connection to arbitrary | |
113 | ports. This can be avoided by checking for the presence of the ':' | |
114 | character in the passed hostname and either indicating an error or | |
115 | truncating the string at that point. | |
bace2124 | 116 | |
0f1c0cf1 VC |
117 | The values returned by BIO_get_conn_hostname(), BIO_get_conn_address(), |
118 | and BIO_get_conn_port() are updated when a connection attempt is made. | |
119 | Before any connection attempt the values returned are those set by the | |
120 | application itself. | |
bace2124 | 121 | |
2273d6b6 DSH |
122 | Applications do not have to call BIO_do_connect() but may wish to do |
123 | so to separate the connection process from other I/O processing. | |
bace2124 DSH |
124 | |
125 | If non blocking I/O is set then retries will be requested as appropriate. | |
126 | ||
127 | It addition to BIO_should_read() and BIO_should_write() it is also | |
128 | possible for BIO_should_io_special() to be true during the initial | |
129 | connection process with the reason BIO_RR_CONNECT. If this is returned | |
130 | then this is an indication that a connection attempt would block, | |
1e4e5492 | 131 | the application should then take appropriate action to wait until |
bace2124 DSH |
132 | the underlying socket has connected and retry the call. |
133 | ||
0f1c0cf1 VC |
134 | BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(), |
135 | BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(), | |
2cb8445a | 136 | BIO_set_conn_ip_family(), BIO_get_conn_ip_family(), |
0f1c0cf1 | 137 | BIO_set_nbio(), and BIO_do_connect() are macros. |
bbdc9c98 | 138 | |
bace2124 DSH |
139 | =head1 RETURN VALUES |
140 | ||
141 | BIO_s_connect() returns the connect BIO method. | |
142 | ||
2cb8445a | 143 | BIO_set_conn_address(), BIO_set_conn_port(), and BIO_set_conn_ip_family() |
5001287c | 144 | return 1 or <=0 if an error occurs. |
2273d6b6 | 145 | |
5001287c | 146 | BIO_set_conn_hostname() returns 1 on success and <=0 on failure. |
0f1c0cf1 VC |
147 | |
148 | BIO_get_conn_address() returns the address information or NULL if none | |
149 | was set. | |
150 | ||
151 | BIO_get_conn_hostname() returns the connected hostname or NULL if | |
2273d6b6 DSH |
152 | none was set. |
153 | ||
2cb8445a VC |
154 | BIO_get_conn_ip_family() returns the address family or -1 if none was set. |
155 | ||
2273d6b6 DSH |
156 | BIO_get_conn_port() returns a string representing the connected |
157 | port or NULL if not set. | |
158 | ||
5001287c | 159 | BIO_set_nbio() returns 1 or <=0 if an error occurs. |
2273d6b6 DSH |
160 | |
161 | BIO_do_connect() returns 1 if the connection was successfully | |
5001287c | 162 | established and <=0 if the connection failed. |
2273d6b6 | 163 | |
cda77422 | 164 | =head1 EXAMPLES |
2273d6b6 DSH |
165 | |
166 | This is example connects to a webserver on the local host and attempts | |
167 | to retrieve a page and copy the result to standard output. | |
168 | ||
169 | ||
170 | BIO *cbio, *out; | |
171 | int len; | |
172 | char tmpbuf[1024]; | |
f672aee4 | 173 | |
2273d6b6 DSH |
174 | cbio = BIO_new_connect("localhost:http"); |
175 | out = BIO_new_fp(stdout, BIO_NOCLOSE); | |
05ea606a RS |
176 | if (BIO_do_connect(cbio) <= 0) { |
177 | fprintf(stderr, "Error connecting to server\n"); | |
178 | ERR_print_errors_fp(stderr); | |
179 | exit(1); | |
180 | } | |
2273d6b6 | 181 | BIO_puts(cbio, "GET / HTTP/1.0\n\n"); |
2947af32 | 182 | for (;;) { |
05ea606a | 183 | len = BIO_read(cbio, tmpbuf, 1024); |
2f8e53d7 | 184 | if (len <= 0) |
05ea606a RS |
185 | break; |
186 | BIO_write(out, tmpbuf, len); | |
2273d6b6 DSH |
187 | } |
188 | BIO_free(cbio); | |
189 | BIO_free(out); | |
bace2124 | 190 | |
bace2124 DSH |
191 | |
192 | =head1 SEE ALSO | |
193 | ||
75f036c6 | 194 | L<BIO_ADDR(3)>, L<BIO_parse_hostserv(3)> |
99ec4fdb | 195 | |
0f1c0cf1 VC |
196 | =head1 HISTORY |
197 | ||
198 | BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(), and BIO_get_conn_ip() | |
199 | were removed in OpenSSL 1.1.0. | |
200 | Use BIO_set_conn_address() and BIO_get_conn_address() instead. | |
201 | ||
e2f92610 RS |
202 | =head1 COPYRIGHT |
203 | ||
aff636a4 | 204 | Copyright 2000-2021 The OpenSSL Project Authors. All Rights Reserved. |
e2f92610 | 205 | |
4746f25a | 206 | Licensed under the Apache License 2.0 (the "License"). You may not use |
e2f92610 RS |
207 | this file except in compliance with the License. You can obtain a copy |
208 | in the file LICENSE in the source distribution or at | |
209 | L<https://www.openssl.org/source/license.html>. | |
210 | ||
211 | =cut |