1BIO_s_connect(3)                    OpenSSL                   BIO_s_connect(3)
2
3
4

NAME

6       BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname,
7       BIO_set_conn_port, BIO_set_conn_ip, BIO_set_conn_int_port,
8       BIO_get_conn_hostname, BIO_get_conn_port, BIO_get_conn_ip,
9       BIO_get_conn_int_port, BIO_set_nbio, BIO_do_connect - connect BIO
10

SYNOPSIS

12        #include <openssl/bio.h>
13
14        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_ip(BIO *b, char *ip);
21        long BIO_set_conn_int_port(BIO *b, char *port);
22        char *BIO_get_conn_hostname(BIO *b);
23        char *BIO_get_conn_port(BIO *b);
24        char *BIO_get_conn_ip(BIO *b);
25        long BIO_get_conn_int_port(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. The hostname can also include the port
59       in the form hostname:port . It is also acceptable to use the form
60       "hostname/any/other/path" or "hostname:port/any/other/path".
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. Currently the list is http, telnet, socks,
66       https, ssl, ftp, gopher and wais.
67
68       BIO_set_conn_ip() sets the IP address to ip using binary form, that is
69       four bytes specifying the IP address in big-endian form.
70
71       BIO_set_conn_int_port() sets the port using port. port should be of
72       type (int *).
73
74       BIO_get_conn_hostname() returns the hostname of the connect BIO or NULL
75       if the BIO is initialized but no hostname is set.  This return value is
76       an internal pointer which should not be modified.
77
78       BIO_get_conn_port() returns the port as a string.
79
80       BIO_get_conn_ip() returns the IP address in binary form.
81
82       BIO_get_conn_int_port() returns the port as an int.
83
84       BIO_set_nbio() sets the non blocking I/O flag to n. If n is zero then
85       blocking I/O is set. If n is 1 then non blocking I/O is set. Blocking
86       I/O is the default. The call to BIO_set_nbio() should be made before
87       the connection is established because non blocking I/O is set during
88       the connect process.
89
90       BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into a
91       single call: that is it creates a new connect BIO with name.
92
93       BIO_do_connect() attempts to connect the supplied BIO. It returns 1 if
94       the connection was established successfully. A zero or negative value
95       is returned if the connection could not be established, the call
96       BIO_should_retry() should be used for non blocking connect BIOs to
97       determine if the call should be retried.
98

NOTES

100       If blocking I/O is set then a non positive return value from any I/O
101       call is caused by an error condition, although a zero return will
102       normally mean that the connection was closed.
103
104       If the port name is supplied as part of the host name then this will
105       override any value set with BIO_set_conn_port(). This may be
106       undesirable if the application does not wish to allow connection to
107       arbitrary ports. This can be avoided by checking for the presence of
108       the ':' character in the passed hostname and either indicating an error
109       or truncating the string at that point.
110
111       The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
112       BIO_get_conn_ip() and BIO_get_conn_int_port() are updated when a
113       connection attempt is made. Before any connection attempt the values
114       returned are those set by the application itself.
115
116       Applications do not have to call BIO_do_connect() but may wish to do so
117       to separate the connection process from other I/O processing.
118
119       If non blocking I/O is set then retries will be requested as
120       appropriate.
121
122       It addition to BIO_should_read() and BIO_should_write() it is also
123       possible for BIO_should_io_special() to be true during the initial
124       connection process with the reason BIO_RR_CONNECT. If this is returned
125       then this is an indication that a connection attempt would block, the
126       application should then take appropriate action to wait until the
127       underlying socket has connected and retry the call.
128
129       BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
130       BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
131       BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
132       BIO_do_connect() are macros.
133

RETURN VALUES

135       BIO_s_connect() returns the connect BIO method.
136
137       BIO_get_fd() returns the socket or -1 if the BIO has not been
138       initialized.
139
140       BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
141       BIO_set_conn_int_port() always return 1.
142
143       BIO_get_conn_hostname() returns the connected hostname or NULL is none
144       was set.
145
146       BIO_get_conn_port() returns a string representing the connected port or
147       NULL if not set.
148
149       BIO_get_conn_ip() returns a pointer to the connected IP address in
150       binary form or all zeros if not set.
151
152       BIO_get_conn_int_port() returns the connected port or 0 if none was
153       set.
154
155       BIO_set_nbio() always returns 1.
156
157       BIO_do_connect() returns 1 if the connection was successfully
158       established and 0 or -1 if the connection failed.
159

EXAMPLE

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        ERR_load_crypto_strings();
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               /* whatever ... */
174               }
175        BIO_puts(cbio, "GET / HTTP/1.0\n\n");
176        for(;;) {
177               len = BIO_read(cbio, tmpbuf, 1024);
178               if(len <= 0) break;
179               BIO_write(out, tmpbuf, len);
180        }
181        BIO_free(cbio);
182        BIO_free(out);
183

SEE ALSO

185       TBA
186
187
188
1891.0.2o                            2019-09-10                  BIO_s_connect(3)
Impressum