1BIO_S_CONNECT(3ossl)                OpenSSL               BIO_S_CONNECT(3ossl)
2
3
4

NAME

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

SYNOPSIS

12        #include <openssl/bio.h>
13
14        const BIO_METHOD *BIO_s_connect(void);
15
16        BIO *BIO_new_connect(const char *name);
17
18        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
27        long BIO_set_nbio(BIO *b, long n);
28
29        long BIO_do_connect(BIO *b);
30

DESCRIPTION

32       BIO_s_connect() returns the connect BIO method. This is a wrapper round
33       the platform's TCP/IP socket connection routines.
34
35       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
39       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
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 connection is
47       shutdown and the socket closed when the BIO is freed.
48
49       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
53       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
56       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
62       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
66       BIO_set_conn_address() sets the address and port information using a
67       BIO_ADDR(3ssl).
68
69       BIO_set_conn_ip_family() sets the IP family.
70
71       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
75       BIO_get_conn_port() returns the port as a string.  This return value is
76       an internal pointer which should not be modified.
77
78       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
81       BIO_get_conn_ip_family() returns the IP family of the connect BIO.
82
83       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
89       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

NOTES

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
105       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
112       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
117       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
120       If non blocking I/O is set then retries will be requested as
121       appropriate.
122
123       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
130       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

RETURN VALUES

136       BIO_s_connect() returns the connect BIO method.
137
138       BIO_set_conn_address(), BIO_set_conn_port(), and
139       BIO_set_conn_ip_family() return 1 or <=0 if an error occurs.
140
141       BIO_set_conn_hostname() returns 1 on success and <=0 on failure.
142
143       BIO_get_conn_address() returns the address information or NULL if none
144       was set.
145
146       BIO_get_conn_hostname() returns the connected hostname or NULL if none
147       was set.
148
149       BIO_get_conn_ip_family() returns the address family or -1 if none was
150       set.
151
152       BIO_get_conn_port() returns a string representing the connected port or
153       NULL if not set.
154
155       BIO_set_nbio() returns 1 or <=0 if an error occurs.
156
157       BIO_do_connect() returns 1 if the connection was successfully
158       established and <=0 if the connection failed.
159

EXAMPLES

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        BIO *cbio, *out;
165        int len;
166        char tmpbuf[1024];
167
168        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

SEE ALSO

186       BIO_ADDR(3), BIO_parse_hostserv(3)
187

HISTORY

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
196       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>.
200
201
202
2033.1.1                             2023-08-31              BIO_S_CONNECT(3ossl)
Impressum