1BIO_s_connect(3) OpenSSL BIO_s_connect(3)
2
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
12 #include <openssl/bio.h>
13 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_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 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. 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 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 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 BIO_set_conn_int_port() sets the port using port. port should be of
72 type (int *).
73 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 BIO_get_conn_port() returns the port as a string.
79 BIO_get_conn_ip() returns the IP address in binary form.
81 BIO_get_conn_int_port() returns the port as an int.
83 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 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 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
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 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 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 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 If non blocking I/O is set then retries will be requested as
120 appropriate.
121 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 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
135 BIO_s_connect() returns the connect BIO method.
136 BIO_get_fd() returns the socket or -1 if the BIO has not been
138 initialized.
139 BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
141 BIO_set_conn_int_port() always return 1.
142 BIO_get_conn_hostname() returns the connected hostname or NULL is none
144 was set.
145 BIO_get_conn_port() returns a string representing the connected port or
147 NULL if not set.
148 BIO_get_conn_ip() returns a pointer to the connected IP address in
150 binary form or all zeros if not set.
151 BIO_get_conn_int_port() returns the connected port or 0 if none was
153 set.
154 BIO_set_nbio() always returns 1.
156 BIO_do_connect() returns 1 if the connection was successfully
158 established and 0 or -1 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 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
185 TBA
1861.0.2o 2018-03-27 BIO_s_connect(3)