1.\" $OpenBSD: BIO_s_connect.3,v 1.11 2018/05/12 20:12:17 schwarze Exp $ 2.\" OpenSSL 186bb907 Apr 13 11:05:13 2015 -0700 3.\" 4.\" This file was written by Dr. Stephen Henson <steve@openssl.org>. 5.\" Copyright (c) 2000, 2015 The OpenSSL Project. All rights reserved. 6.\" 7.\" Redistribution and use in source and binary forms, with or without 8.\" modification, are permitted provided that the following conditions 9.\" are met: 10.\" 11.\" 1. Redistributions of source code must retain the above copyright 12.\" notice, this list of conditions and the following disclaimer. 13.\" 14.\" 2. Redistributions in binary form must reproduce the above copyright 15.\" notice, this list of conditions and the following disclaimer in 16.\" the documentation and/or other materials provided with the 17.\" distribution. 18.\" 19.\" 3. All advertising materials mentioning features or use of this 20.\" software must display the following acknowledgment: 21.\" "This product includes software developed by the OpenSSL Project 22.\" for use in the OpenSSL Toolkit. (http://www.openssl.org/)" 23.\" 24.\" 4. The names "OpenSSL Toolkit" and "OpenSSL Project" must not be used to 25.\" endorse or promote products derived from this software without 26.\" prior written permission. For written permission, please contact 27.\" openssl-core@openssl.org. 28.\" 29.\" 5. Products derived from this software may not be called "OpenSSL" 30.\" nor may "OpenSSL" appear in their names without prior written 31.\" permission of the OpenSSL Project. 32.\" 33.\" 6. Redistributions of any form whatsoever must retain the following 34.\" acknowledgment: 35.\" "This product includes software developed by the OpenSSL Project 36.\" for use in the OpenSSL Toolkit (http://www.openssl.org/)" 37.\" 38.\" THIS SOFTWARE IS PROVIDED BY THE OpenSSL PROJECT ``AS IS'' AND ANY 39.\" EXPRESSED OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE 40.\" IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR 41.\" PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE OpenSSL PROJECT OR 42.\" ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, 43.\" SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT 44.\" NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; 45.\" LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) 46.\" HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, 47.\" STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) 48.\" ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED 49.\" OF THE POSSIBILITY OF SUCH DAMAGE. 50.\" 51.Dd $Mdocdate: May 12 2018 $ 52.Dt BIO_S_CONNECT 3 53.Os 54.Sh NAME 55.Nm BIO_s_connect , 56.Nm BIO_new_connect , 57.Nm BIO_set_conn_hostname , 58.Nm BIO_set_conn_port , 59.Nm BIO_set_conn_ip , 60.Nm BIO_set_conn_int_port , 61.Nm BIO_get_conn_hostname , 62.Nm BIO_get_conn_port , 63.Nm BIO_get_conn_ip , 64.Nm BIO_get_conn_int_port , 65.Nm BIO_set_nbio , 66.Nm BIO_do_connect 67.Nd connect BIO 68.Sh SYNOPSIS 69.In openssl/bio.h 70.Ft const BIO_METHOD * 71.Fo BIO_s_connect 72.Fa void 73.Fc 74.Ft BIO * 75.Fo BIO_new_connect 76.Fa "const char *name" 77.Fc 78.Ft long 79.Fo BIO_set_conn_hostname 80.Fa "BIO *b" 81.Fa "char *name" 82.Fc 83.Ft long 84.Fo BIO_set_conn_port 85.Fa "BIO *b" 86.Fa "char *port" 87.Fc 88.Ft long 89.Fo BIO_set_conn_ip 90.Fa "BIO *b" 91.Fa "char *ip" 92.Fc 93.Ft long 94.Fo BIO_set_conn_int_port 95.Fa "BIO *b" 96.Fa "char *port" 97.Fc 98.Ft char * 99.Fo BIO_get_conn_hostname 100.Fa "BIO *b" 101.Fc 102.Ft char * 103.Fo BIO_get_conn_port 104.Fa "BIO *b" 105.Fc 106.Ft char * 107.Fo BIO_get_conn_ip 108.Fa "BIO *b" 109.Fa "dummy" 110.Fc 111.Ft long 112.Fo BIO_get_conn_int_port 113.Fa "BIO *b" 114.Fa "int port" 115.Fc 116.Ft long 117.Fo BIO_set_nbio 118.Fa "BIO *b" 119.Fa "long n" 120.Fc 121.Ft int 122.Fo BIO_do_connect 123.Fa "BIO *b" 124.Fc 125.Sh DESCRIPTION 126.Fn BIO_s_connect 127returns the connect BIO method. 128This is a wrapper around the platform's TCP/IP socket connection routines. 129.Pp 130Using connect BIOs, TCP/IP connections can be made and data 131transferred using only BIO routines. 132In this way any platform specific operations 133are hidden by the BIO abstraction. 134.Pp 135Read and write operations on a connect BIO will perform I/O 136on the underlying connection. 137If no connection is established and the port and hostname (see below) 138is set up properly, then a connection is established first. 139.Pp 140Connect BIOs support 141.Xr BIO_puts 3 142but not 143.Xr BIO_gets 3 . 144.Pp 145If the close flag is set on a connect BIO, then any active connection 146is shutdown and the socket closed when the BIO is freed. 147.Pp 148Calling 149.Xr BIO_reset 3 150on a connect BIO will close any active connection and reset the BIO 151into a state where it can connect to the same host again. 152.Pp 153.Xr BIO_get_fd 3 154places the underlying socket in 155.Fa c 156if it is not 157.Dv NULL 158and also returns the socket. 159If 160.Fa c 161is not 162.Dv NULL 163it should be of type 164.Vt "int *" . 165.Pp 166.Fn BIO_set_conn_hostname 167uses the string 168.Fa name 169to set the hostname. 170The hostname can be an IP address. 171The hostname can also include the port in the form 172.Ar hostname : Ns Ar port . 173It is also acceptable to use the forms 174.Ar hostname Ns / Ns Pa any/other/path 175or 176.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path . 177.Pp 178.Fn BIO_set_conn_port 179sets the port to 180.Fa port . 181.Fa port 182is looked up as a service using 183.Xr getaddrinfo 3 184.Pp 185.Fn BIO_set_conn_ip 186sets the IP address to 187.Fa ip 188using binary form i.e. four bytes specifying the IP address 189in big-endian form. 190.Pp 191.Fn BIO_set_conn_int_port 192sets the port using 193.Fa port . 194.Fa port 195should 196be of type 197.Vt "int *" . 198.Pp 199.Fn BIO_get_conn_hostname 200returns the hostname of the connect BIO or 201.Dv NULL 202if the BIO is initialized but no hostname is set. 203This return value is an internal pointer which should not be modified. 204.Pp 205.Fn BIO_get_conn_port 206returns the port as a string. 207This return value is an internal pointer which should not be modified. 208.Pp 209.Fn BIO_get_conn_ip 210returns the IP address in binary form. 211.Pp 212.Fn BIO_get_conn_int_port 213returns the port as an 214.Vt int . 215.Pp 216.Fn BIO_set_nbio 217sets the non-blocking I/O flag to 218.Fa n . 219If 220.Fa n 221is zero then blocking I/O is set. 222If 223.Fa n 224is 1 then non-blocking I/O is set. 225Blocking I/O is the default. 226The call to 227.Fn BIO_set_nbio 228should be made before the connection is established 229because non-blocking I/O is set during the connect process. 230.Pp 231.Fn BIO_new_connect 232combines 233.Xr BIO_new 3 234and 235.Fn BIO_set_conn_hostname 236into a single call. 237It creates a new connect BIO with 238.Fa name . 239.Pp 240.Fn BIO_do_connect 241attempts to connect the supplied BIO. 242It returns 1 if the connection was established successfully. 243A zero or negative value is returned if the connection 244could not be established. 245The call 246.Xr BIO_should_retry 3 247should be used for non-blocking connect BIOs 248to determine if the call should be retried. 249.Pp 250If blocking I/O is set then a non-positive return value from any 251I/O call is caused by an error condition, although a zero return 252will normally mean that the connection was closed. 253.Pp 254If the port name is supplied as part of the host name then this will 255override any value set with 256.Fn BIO_set_conn_port . 257This may be undesirable if the application does not wish to allow 258connection to arbitrary ports. 259This can be avoided by checking for the presence of the 260.Sq \&: 261character in the passed hostname and either indicating an error 262or truncating the string at that point. 263.Pp 264The values returned by 265.Fn BIO_get_conn_hostname , 266.Fn BIO_get_conn_port , 267.Fn BIO_get_conn_ip , 268and 269.Fn BIO_get_conn_int_port 270are updated when a connection attempt is made. 271Before any connection attempt the values returned 272are those set by the application itself. 273.Pp 274Applications do not have to call 275.Fn BIO_do_connect 276but may wish to do so to separate the connection process 277from other I/O processing. 278.Pp 279If non-blocking I/O is set, 280then retries will be requested as appropriate. 281.Pp 282In addition to 283.Xr BIO_should_read 3 284and 285.Xr BIO_should_write 3 286it is also possible for 287.Xr BIO_should_io_special 3 288to be true during the initial connection process with the reason 289.Dv BIO_RR_CONNECT . 290If this is returned, it is an indication 291that a connection attempt would block. 292The application should then take appropriate action to wait 293until the underlying socket has connected and retry the call. 294.Pp 295.Fn BIO_set_conn_hostname , 296.Fn BIO_set_conn_port , 297.Fn BIO_set_conn_ip , 298.Fn BIO_set_conn_int_port , 299.Fn BIO_get_conn_hostname , 300.Fn BIO_get_conn_port , 301.Fn BIO_get_conn_ip , 302.Fn BIO_get_conn_int_port , 303.Fn BIO_set_nbio , 304and 305.Fn BIO_do_connect 306are macros. 307.Sh RETURN VALUES 308.Fn BIO_s_connect 309returns the connect BIO method. 310.Pp 311.Xr BIO_get_fd 3 312returns the socket or -1 if the BIO has not been initialized. 313.Pp 314.Fn BIO_set_conn_hostname , 315.Fn BIO_set_conn_port , 316.Fn BIO_set_conn_ip , 317and 318.Fn BIO_set_conn_int_port 319always return 1. 320.Pp 321.Fn BIO_get_conn_hostname 322returns the connected hostname or 323.Dv NULL 324if none is set. 325.Pp 326.Fn BIO_get_conn_port 327returns a string representing the connected port or 328.Dv NULL 329if not set. 330.Pp 331.Fn BIO_get_conn_ip 332returns a pointer to the connected IP address in binary form 333or all zeros if not set. 334.Pp 335.Fn BIO_get_conn_int_port 336returns the connected port or 0 if none was set. 337.Pp 338.Fn BIO_set_nbio 339always returns 1. 340.Pp 341.Fn BIO_do_connect 342returns 1 if the connection was successfully 343established and 0 or -1 if the connection failed. 344.Sh EXAMPLES 345This example connects to a webserver on the local host and attempts 346to retrieve a page and copy the result to standard output. 347.Bd -literal -offset 2n 348BIO *cbio, *out; 349int len; 350char tmpbuf[1024]; 351 352ERR_load_crypto_strings(); 353cbio = BIO_new_connect("localhost:http"); 354out = BIO_new_fp(stdout, BIO_NOCLOSE); 355if (BIO_do_connect(cbio) <= 0) { 356 fprintf(stderr, "Error connecting to server\en"); 357 ERR_print_errors_fp(stderr); 358 /* whatever ... */ 359} 360BIO_puts(cbio, "GET / HTTP/1.0\en\en"); 361for(;;) { 362 len = BIO_read(cbio, tmpbuf, 1024); 363 if (len <= 0) 364 break; 365 BIO_write(out, tmpbuf, len); 366} 367BIO_free(cbio); 368BIO_free(out); 369.Ed 370.Sh SEE ALSO 371.Xr BIO_new 3 372.Sh HISTORY 373.Fn BIO_s_connect , 374.Fn BIO_new_connect , 375.Fn BIO_set_nbio , 376and 377.Fn BIO_do_connect 378first appeared in SSLeay 0.8.0. 379.Fn BIO_set_conn_hostname , 380.Fn BIO_set_conn_port , 381.Fn BIO_set_conn_ip , 382.Fn BIO_set_conn_int_port , 383.Fn BIO_get_conn_hostname , 384.Fn BIO_get_conn_port , 385.Fn BIO_get_conn_ip , 386and 387.Fn BIO_get_conn_int_port 388first appeared in SSLeay 0.9.0. 389All these functions have been available since 390.Ox 2.4 . 391