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