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

NAME

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

SYNOPSIS

12        #include <openssl/bio.h>
13
14        const BIO_METHOD * BIO_s_connect(void);
15
16        BIO *BIO_new_connect(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        int 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_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
57       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
62       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
68       BIO_set_conn_address() sets the address and port information using a
69       BIO_ADDR(3ssl).
70
71       BIO_set_conn_ip_family() sets the IP family.
72
73       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
77       BIO_get_conn_port() returns the port as a string.  This return value is
78       an internal pointer which should not be modified.
79
80       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
83       BIO_get_conn_ip_family() returns the IP family of the connect BIO.
84
85       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
91       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
94       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

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_get_fd() returns the socket or -1 if the BIO has not been
139       initialized.
140
141       BIO_set_conn_address(), BIO_set_conn_port(), and
142       BIO_set_conn_ip_family() always return 1.
143
144       BIO_set_conn_hostname() returns 1 on success and 0 on failure.
145
146       BIO_get_conn_address() returns the address information or NULL if none
147       was set.
148
149       BIO_get_conn_hostname() returns the connected hostname or NULL if none
150       was set.
151
152       BIO_get_conn_ip_family() returns the address family or -1 if none was
153       set.
154
155       BIO_get_conn_port() returns a string representing the connected port or
156       NULL if not set.
157
158       BIO_set_nbio() always returns 1.
159
160       BIO_do_connect() returns 1 if the connection was successfully
161       established and 0 or -1 if the connection failed.
162

EXAMPLES

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

SEE ALSO

189       BIO_ADDR(3)
190

HISTORY

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
199       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>.
203
204
205
2061.1.1l                            2021-09-15                  BIO_S_CONNECT(3)
Impressum