path: root/lib/libcrypto/man/BIO_s_connect.3

.\"	$OpenBSD: BIO_s_connect.3,v 1.3 2016/11/07 15:52:47 jmc Exp $
.\"
.Dd $Mdocdate: November 7 2016 $
.Dt BIO_S_CONNECT 3
.Os
.Sh NAME
.Nm BIO_s_connect ,
.Nm BIO_new_connect ,
.Nm BIO_set_conn_hostname ,
.Nm BIO_set_conn_port ,
.Nm BIO_set_conn_ip ,
.Nm BIO_set_conn_int_port ,
.Nm BIO_get_conn_hostname ,
.Nm BIO_get_conn_port ,
.Nm BIO_get_conn_ip ,
.Nm BIO_get_conn_int_port ,
.Nm BIO_set_nbio ,
.Nm BIO_do_connect
.Nd connect BIO
.Sh SYNOPSIS
.In openssl/bio.h
.Ft BIO_METHOD *
.Fo BIO_s_connect
.Fa void
.Fc
.Ft BIO *
.Fo BIO_new_connect
.Fa "char *name"
.Fc
.Ft long
.Fo BIO_set_conn_hostname
.Fa "BIO *b"
.Fa "char *name"
.Fc
.Ft long
.Fo BIO_set_conn_port
.Fa "BIO *b"
.Fa "char *port"
.Fc
.Ft long
.Fo BIO_set_conn_ip
.Fa "BIO *b"
.Fa "char *ip"
.Fc
.Ft long
.Fo BIO_set_conn_int_port
.Fa "BIO *b"
.Fa "char *port"
.Fc
.Ft char *
.Fo BIO_get_conn_hostname
.Fa "BIO *b"
.Fc
.Ft char *
.Fo BIO_get_conn_port
.Fa "BIO *b"
.Fc
.Ft char *
.Fo BIO_get_conn_ip
.Fa "BIO *b"
.Fa "dummy"
.Fc
.Ft long
.Fo BIO_get_conn_int_port
.Fa "BIO *b"
.Fa "int port"
.Fc
.Ft long
.Fo BIO_set_nbio
.Fa "BIO *b"
.Fa "long n"
.Fc
.Ft int
.Fo BIO_do_connect
.Fa "BIO *b"
.Fc
.Sh DESCRIPTION
.Fn BIO_s_connect
returns the connect BIO method.
This is a wrapper around the platform's TCP/IP socket connection routines.
.Pp
Using connect BIOs, TCP/IP connections can be made and data
transferred using only BIO routines.
In this way any platform specific operations
are hidden by the BIO abstraction.
.Pp
Read and write operations on a connect BIO will perform I/O
on the underlying connection.
If no connection is established and the port and hostname (see below)
is set up properly, then a connection is established first.
.Pp
Connect BIOs support
.Xr BIO_puts 3
but not
.Xr BIO_gets 3 .
.Pp
If the close flag is set on a connect BIO, then any active connection
is shutdown and the socket closed when the BIO is freed.
.Pp
Calling
.Xr BIO_reset 3
on a connect BIO will close any active connection and reset the BIO
into a state where it can connect to the same host again.
.Pp
.Xr BIO_get_fd 3
places the underlying socket in
.Fa c
if it is not
.Dv NULL
and also returns the socket.
If
.Fa c
is not
.Dv NULL
it should be of type
.Vt "int *" .
.Pp
.Fn BIO_set_conn_hostname
uses the string
.Fa name
to set the hostname.
The hostname can be an IP address.
The hostname can also include the port in the form
.Ar hostname : Ns Ar port .
It is also acceptable to use the forms
.Ar hostname Ns / Ns Pa any/other/path
or
.Ar hostname : Ns Ar port Ns / Ns Pa any/other/path .
.Pp
.Fn BIO_set_conn_port
sets the port to
.Fa port .
.Fa port
can be the numerical form or a string such as
.Cm http .
A string will be looked up first using
.Xr getservbyname 3
on the host platform, but if that fails
a built-in table of port names will be used.
Currently the list is
.Cm http ,
.Cm telnet ,
.Cm socks ,
.Cm https ,
.Cm ssl ,
.Cm ftp ,
.Cm gopher ,
and
.Cm wais .
.Pp
.Fn BIO_set_conn_ip
sets the IP address to
.Fa ip
using binary form i.e. four bytes specifying the IP address
in big-endian form.
.Pp
.Fn BIO_set_conn_int_port
sets the port using
.Fa port .
.Fa port
should
be of type
.Vt "int *" .
.Pp
.Fn BIO_get_conn_hostname
returns the hostname of the connect BIO or
.Dv NULL
if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
.Pp
.Fn BIO_get_conn_port
returns the port as a string.
.Pp
.Fn BIO_get_conn_ip
returns the IP address in binary form.
.Pp
.Fn BIO_get_conn_int_port
returns the port as an
.Vt int .
.Pp
.Fn BIO_set_nbio
sets the non-blocking I/O flag to
.Fa n .
If
.Fa n
is zero then blocking I/O is set.
If
.Fa n
is 1 then non-blocking I/O is set.
Blocking I/O is the default.
The call to
.Fn BIO_set_nbio
should be made before the connection is established
because non-blocking I/O is set during the connect process.
.Pp
.Fn BIO_new_connect
combines
.Xr BIO_new 3
and
.Fn BIO_set_conn_hostname
into a single call.
It creates a new connect BIO with
.Fa name .
.Pp
.Fn BIO_do_connect
attempts to connect the supplied BIO.
It returns 1 if the connection was established successfully.
A zero or negative value is returned if the connection
could not be established.
The call
.Xr BIO_should_retry 3
should be used for non-blocking connect BIOs
to determine if the call should be retried.
.Pp
If blocking I/O is set then a non-positive return value from any
I/O call is caused by an error condition, although a zero return
will normally mean that the connection was closed.
.Pp
If the port name is supplied as part of the host name then this will
override any value set with
.Fn BIO_set_conn_port .
This may be undesirable if the application does not wish to allow
connection to arbitrary ports.
This can be avoided by checking for the presence of the
.Sq \&:
character in the passed hostname and either indicating an error
or truncating the string at that point.
.Pp
The values returned by
.Fn BIO_get_conn_hostname ,
.Fn BIO_get_conn_port ,
.Fn BIO_get_conn_ip ,
and
.Fn BIO_get_conn_int_port
are updated when a connection attempt is made.
Before any connection attempt the values returned
are those set by the application itself.
.Pp
Applications do not have to call
.Fn BIO_do_connect
but may wish to do so to separate the connection process
from other I/O processing.
.Pp
If non-blocking I/O is set,
then retries will be requested as appropriate.
.Pp
In addition to
.Xr BIO_should_read 3
and
.Xr BIO_should_write 3
it is also possible for
.Xr BIO_should_io_special 3
to be true during the initial connection process with the reason
.Dv BIO_RR_CONNECT .
If this is returned, it is an indication
that a connection attempt would block.
The application should then take appropriate action to wait
until the underlying socket has connected and retry the call.
.Pp
.Fn BIO_set_conn_hostname ,
.Fn BIO_set_conn_port ,
.Fn BIO_set_conn_ip ,
.Fn BIO_set_conn_int_port ,
.Fn BIO_get_conn_hostname ,
.Fn BIO_get_conn_port ,
.Fn BIO_get_conn_ip ,
.Fn BIO_get_conn_int_port ,
.Fn BIO_set_nbio ,
and
.Fn BIO_do_connect
are macros.
.Sh RETURN VALUES
.Fn BIO_s_connect
returns the connect BIO method.
.Pp
.Xr BIO_get_fd 3
returns the socket or -1 if the BIO has not been initialized.
.Pp
.Fn BIO_set_conn_hostname ,
.Fn BIO_set_conn_port ,
.Fn BIO_set_conn_ip ,
and
.Fn BIO_set_conn_int_port
always return 1.
.Pp
.Fn BIO_get_conn_hostname
returns the connected hostname or
.Dv NULL
if none is set.
.Pp
.Fn BIO_get_conn_port
returns a string representing the connected port or
.Dv NULL
if not set.
.Pp
.Fn BIO_get_conn_ip
returns a pointer to the connected IP address in binary form
or all zeros if not set.
.Pp
.Fn BIO_get_conn_int_port
returns the connected port or 0 if none was set.
.Pp
.Fn BIO_set_nbio
always returns 1.
.Pp
.Fn BIO_do_connect
returns 1 if the connection was successfully
established and 0 or -1 if the connection failed.
.Sh EXAMPLES
This example connects to a webserver on the local host and attempts
to retrieve a page and copy the result to standard output.
.Bd -literal -offset 2n
BIO *cbio, *out;
int len;
char tmpbuf[1024];

ERR_load_crypto_strings();
cbio = BIO_new_connect("localhost:http");
out = BIO_new_fp(stdout, BIO_NOCLOSE);
if (BIO_do_connect(cbio) <= 0) {
	fprintf(stderr, "Error connecting to server\en");
	ERR_print_errors_fp(stderr);
	/* whatever ... */
}
BIO_puts(cbio, "GET / HTTP/1.0\en\en");
for(;;) {
	len = BIO_read(cbio, tmpbuf, 1024);
	if (len <= 0)
		break;
	BIO_write(out, tmpbuf, len);
}
BIO_free(cbio);
BIO_free(out);
.Ed