1BIO_S_CONNECT(3) OpenSSL BIO_S_CONNECT(3)
2
6 BIO_set_conn_address, BIO_get_conn_address, BIO_s_connect,
7 BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
8 BIO_set_conn_ip_family, BIO_get_conn_ip_family, BIO_get_conn_hostname,
9 BIO_get_conn_port, BIO_set_nbio, BIO_do_connect - connect BIO
10
12 #include <openssl/bio.h>
13 const BIO_METHOD * BIO_s_connect(void);
15 BIO *BIO_new_connect(char *name);
17 long BIO_set_conn_hostname(BIO *b, char *name);
19 long BIO_set_conn_port(BIO *b, char *port);
20 long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
21 long BIO_set_conn_ip_family(BIO *b, long family);
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);
25 const long BIO_get_conn_ip_family(BIO *b);
26 long BIO_set_nbio(BIO *b, long n);
28 int BIO_do_connect(BIO *b);
30
32 BIO_s_connect() returns the connect BIO method. This is a wrapper round
33 the platform's TCP/IP socket connection routines.
34 Using connect BIOs, TCP/IP connections can be made and data transferred
36 using only BIO routines. In this way any platform specific operations
37 are hidden by the BIO abstraction.
38 Read and write operations on a connect BIO will perform I/O on the
40 underlying connection. If no connection is established and the port and
41 hostname (see below) is set up properly then a connection is
42 established first.
43 Connect BIOs support BIO_puts() but not BIO_gets().
45 If the close flag is set on a connect BIO then any active connection is
47 shutdown and the socket closed when the BIO is freed.
48 Calling BIO_reset() on a connect BIO will close any active connection
50 and reset the BIO into a state where it can connect to the same host
51 again.
52 BIO_get_fd() places the underlying socket in c if it is not NULL, it
54 also returns the socket . If c is not NULL it should be of type (int
55 *).
56 BIO_set_conn_hostname() uses the string name to set the hostname. The
58 hostname can be an IP address; if the address is an IPv6 one, it must
59 be enclosed with brackets. The hostname can also include the port in
60 the form hostname:port.
61 BIO_set_conn_port() sets the port to port. port can be the numerical
63 form or a string such as "http". A string will be looked up first using
64 getservbyname() on the host platform but if that fails a standard table
65 of port names will be used. This internal list is http, telnet, socks,
66 https, ssl, ftp, and gopher.
67 BIO_set_conn_address() sets the address and port information using a
69 BIO_ADDR(3ssl).
70 BIO_set_conn_ip_family() sets the IP family.
72 BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL
74 if the BIO is initialized but no hostname is set. This return value is
75 an internal pointer which should not be modified.
76 BIO_get_conn_port() returns the port as a string. This return value is
78 an internal pointer which should not be modified.
79 BIO_get_conn_address() returns the address information as a BIO_ADDR.
81 This return value is an internal pointer which should not be modified.
82 BIO_get_conn_ip_family() returns the IP family of the connect BIO.
84 BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then
86 blocking I/O is set. If n is 1 then non blocking I/O is set. Blocking
87 I/O is the default. The call to BIO_set_nbio() should be made before
88 the connection is established because non blocking I/O is set during
89 the connect process.
90 BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a
92 single call: that is it creates a new connect BIO with name.
93 BIO_do_connect() attempts to connect the supplied BIO. It returns 1 if
95 the connection was established successfully. A zero or negative value
96 is returned if the connection could not be established, the call
97 BIO_should_retry() should be used for non blocking connect BIOs to
98 determine if the call should be retried.
99
101 If blocking I/O is set then a non positive return value from any I/O
102 call is caused by an error condition, although a zero return will
103 normally mean that the connection was closed.
104 If the port name is supplied as part of the hostname then this will
106 override any value set with BIO_set_conn_port(). This may be
107 undesirable if the application does not wish to allow connection to
108 arbitrary ports. This can be avoided by checking for the presence of
109 the ':' character in the passed hostname and either indicating an error
110 or truncating the string at that point.
111 The values returned by BIO_get_conn_hostname(), BIO_get_conn_address(),
113 and BIO_get_conn_port() are updated when a connection attempt is made.
114 Before any connection attempt the values returned are those set by the
115 application itself.
116 Applications do not have to call BIO_do_connect() but may wish to do so
118 to separate the connection process from other I/O processing.
119 If non blocking I/O is set then retries will be requested as
121 appropriate.
122 It addition to BIO_should_read() and BIO_should_write() it is also
124 possible for BIO_should_io_special() to be true during the initial
125 connection process with the reason BIO_RR_CONNECT. If this is returned
126 then this is an indication that a connection attempt would block, the
127 application should then take appropriate action to wait until the
128 underlying socket has connected and retry the call.
129 BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_get_conn_hostname(),
131 BIO_set_conn_address(), BIO_get_conn_port(), BIO_get_conn_address(),
132 BIO_set_conn_ip_family(), BIO_get_conn_ip_family(), BIO_set_nbio(), and
133 BIO_do_connect() are macros.
134
136 BIO_s_connect() returns the connect BIO method.
137 BIO_get_fd() returns the socket or -1 if the BIO has not been
139 initialized.
140 BIO_set_conn_address(), BIO_set_conn_port(), and
142 BIO_set_conn_ip_family() always return 1.
143 BIO_set_conn_hostname() returns 1 on success and 0 on failure.
145 BIO_get_conn_address() returns the address information or NULL if none
147 was set.
148 BIO_get_conn_hostname() returns the connected hostname or NULL if none
150 was set.
151 BIO_get_conn_ip_family() returns the address family or -1 if none was
153 set.
154 BIO_get_conn_port() returns a string representing the connected port or
156 NULL if not set.
157 BIO_set_nbio() always returns 1.
159 BIO_do_connect() returns 1 if the connection was successfully
161 established and 0 or -1 if the connection failed.
162
164 This is example connects to a webserver on the local host and attempts
165 to retrieve a page and copy the result to standard output.
166 BIO *cbio, *out;
168 int len;
169 char tmpbuf[1024];
170 cbio = BIO_new_connect("localhost:http");
172 out = BIO_new_fp(stdout, BIO_NOCLOSE);
173 if (BIO_do_connect(cbio) <= 0) {
174 fprintf(stderr, "Error connecting to server\n");
175 ERR_print_errors_fp(stderr);
176 exit(1);
177 }
178 BIO_puts(cbio, "GET / HTTP/1.0\n\n");
179 for (;;) {
180 len = BIO_read(cbio, tmpbuf, 1024);
181 if (len <= 0)
182 break;
183 BIO_write(out, tmpbuf, len);
184 }
185 BIO_free(cbio);
186 BIO_free(out);
187
189 BIO_ADDR(3)
190
192 BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(),
193 and BIO_get_conn_ip() were removed in OpenSSL 1.1.0. Use
194 BIO_set_conn_address() and BIO_get_conn_address() instead.
195
197 Copyright 2000-2020 The OpenSSL Project Authors. All Rights Reserved.
198 Licensed under the OpenSSL license (the "License"). You may not use
200 this file except in compliance with the License. You can obtain a copy
201 in the file LICENSE in the source distribution or at
202 <https://www.openssl.org/source/license.html>.
2031.1.1l 2021-09-15 BIO_S_CONNECT(3)