1BIO_S_CONNECT(3ossl) OpenSSL BIO_S_CONNECT(3ossl)
2
6 BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname,
7 BIO_set_conn_port, BIO_set_conn_address, BIO_set_conn_ip_family,
8 BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_address,
9 BIO_get_conn_ip_family, 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(const 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 long 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_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a
54 single call: that is it creates a new connect BIO with hostname name.
55 BIO_set_conn_hostname() uses the string name to set the hostname. The
57 hostname can be an IP address; if the address is an IPv6 one, it must
58 be enclosed with brackets "[" and "]". The hostname can also include
59 the port in the form hostname:port; see BIO_parse_hostserv(3) and
60 BIO_set_conn_port() for details.
61 BIO_set_conn_port() sets the port to port. port can be the numerical
63 form or a service string such as "http", which will be mapped to a port
64 number using the system function getservbyname().
65 BIO_set_conn_address() sets the address and port information using a
67 BIO_ADDR(3ssl).
68 BIO_set_conn_ip_family() sets the IP family.
70 BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL
72 if the BIO is initialized but no hostname is set. This return value is
73 an internal pointer which should not be modified.
74 BIO_get_conn_port() returns the port as a string. This return value is
76 an internal pointer which should not be modified.
77 BIO_get_conn_address() returns the address information as a BIO_ADDR.
79 This return value is an internal pointer which should not be modified.
80 BIO_get_conn_ip_family() returns the IP family of the connect BIO.
82 BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then
84 blocking I/O is set. If n is 1 then non blocking I/O is set. Blocking
85 I/O is the default. The call to BIO_set_nbio() should be made before
86 the connection is established because non blocking I/O is set during
87 the connect process.
88 BIO_do_connect() attempts to connect the supplied BIO. This performs
90 an SSL/TLS handshake as far as supported by the BIO. For non-SSL BIOs
91 the connection is done typically at TCP level. If domain name
92 resolution yields multiple IP addresses all of them are tried after
93 connect() failures. The function returns 1 if the connection was
94 established successfully. A zero or negative value is returned if the
95 connection could not be established. The call BIO_should_retry()
96 should be used for non blocking connect BIOs to determine if the call
97 should be retried. If a connection has already been established this
98 call has no effect.
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_set_conn_address(), BIO_set_conn_port(), and
139 BIO_set_conn_ip_family() return 1 or <=0 if an error occurs.
140 BIO_set_conn_hostname() returns 1 on success and <=0 on failure.
142 BIO_get_conn_address() returns the address information or NULL if none
144 was set.
145 BIO_get_conn_hostname() returns the connected hostname or NULL if none
147 was set.
148 BIO_get_conn_ip_family() returns the address family or -1 if none was
150 set.
151 BIO_get_conn_port() returns a string representing the connected port or
153 NULL if not set.
154 BIO_set_nbio() returns 1 or <=0 if an error occurs.
156 BIO_do_connect() returns 1 if the connection was successfully
158 established and <=0 if the connection failed.
159
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 BIO *cbio, *out;
165 int len;
166 char tmpbuf[1024];
167 cbio = BIO_new_connect("localhost:http");
169 out = BIO_new_fp(stdout, BIO_NOCLOSE);
170 if (BIO_do_connect(cbio) <= 0) {
171 fprintf(stderr, "Error connecting to server\n");
172 ERR_print_errors_fp(stderr);
173 exit(1);
174 }
175 BIO_puts(cbio, "GET / HTTP/1.0\n\n");
176 for (;;) {
177 len = BIO_read(cbio, tmpbuf, 1024);
178 if (len <= 0)
179 break;
180 BIO_write(out, tmpbuf, len);
181 }
182 BIO_free(cbio);
183 BIO_free(out);
184
186 BIO_ADDR(3), BIO_parse_hostserv(3)
187
189 BIO_set_conn_int_port(), BIO_get_conn_int_port(), BIO_set_conn_ip(),
190 and BIO_get_conn_ip() were removed in OpenSSL 1.1.0. Use
191 BIO_set_conn_address() and BIO_get_conn_address() instead.
192
194 Copyright 2000-2023 The OpenSSL Project Authors. All Rights Reserved.
195 Licensed under the Apache License 2.0 (the "License"). You may not use
197 this file except in compliance with the License. You can obtain a copy
198 in the file LICENSE in the source distribution or at
199 <https://www.openssl.org/source/license.html>.
2003.1.1 2023-08-31 BIO_S_CONNECT(3ossl)