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