=head1 NAME
-BIO_s_connect - connect BIO
+BIO_s_connect, BIO_new_connect, BIO_set_conn_hostname, BIO_set_conn_port,
+BIO_set_conn_ip, BIO_set_conn_int_port, BIO_get_conn_hostname,
+BIO_get_conn_port, BIO_get_conn_ip, BIO_get_conn_int_port,
+BIO_set_nbio, BIO_do_connect - connect BIO
=head1 SYNOPSIS
#include <openssl/bio.h>
- BIO_METHOD * BIO_s_connect(void);
+ const BIO_METHOD * BIO_s_connect(void);
- #define BIO_set_conn_hostname(b,name) BIO_ctrl(b,BIO_C_SET_CONNECT,0,(char *)name)
- #define BIO_set_conn_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,1,(char *)port)
- #define BIO_set_conn_ip(b,ip) BIO_ctrl(b,BIO_C_SET_CONNECT,2,(char *)ip)
- #define BIO_set_conn_int_port(b,port) BIO_ctrl(b,BIO_C_SET_CONNECT,3,(char *)port)
- #define BIO_get_conn_hostname(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,0)
- #define BIO_get_conn_port(b) BIO_ptr_ctrl(b,BIO_C_GET_CONNECT,1)
- #define BIO_get_conn_ip(b,ip) BIO_ptr_ctrl(b,BIO_C_SET_CONNECT,2)
- #define BIO_get_conn_int_port(b,port) BIO_int_ctrl(b,BIO_C_SET_CONNECT,3,port)
+ BIO *BIO_new_connect(char *name);
- #define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL)
+ long BIO_set_conn_hostname(BIO *b, char *name);
+ long BIO_set_conn_port(BIO *b, char *port);
+ long BIO_set_conn_address(BIO *b, BIO_ADDR *addr);
+ const char *BIO_get_conn_hostname(BIO *b);
+ const char *BIO_get_conn_port(BIO *b);
+ const BIO_ADDR *BIO_get_conn_address(BIO *b);
- #define BIO_do_connect(b) BIO_do_handshake(b)
+ long BIO_set_nbio(BIO *b, long n);
+
+ int BIO_do_connect(BIO *b);
=head1 DESCRIPTION
BIO_s_connect() returns the connect BIO method. This is a wrapper
round the platform's TCP/IP socket connection routines.
-Using connect BIOs TCP/IP connections can be made and data
+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.
it also returns the socket . If B<c> is not NULL it should be of
type (int *).
-BIO_set_conn_hostname() uses the string B<name> to set the hostname
-The hostname can be an IP address. The hostname can also include the
-port in the form hostname:port . It is also acceptable to use the
-form "hostname/any/other/path" or "hostname:port/any/other/path".
+BIO_set_conn_hostname() uses the string B<name> to set the hostname.
+The hostname can be an IP address; if the address is an IPv6 one, it
+must be enclosed with brackets. The hostname can also include the
+port in the form hostname:port.
BIO_set_conn_port() sets the port to B<port>. B<port> can be the
numerical form or a string such as "http". A string will be looked
up first using getservbyname() on the host platform but if that
-fails a standard table of port names will be used. Currently the
-list is http, telnet, socks, https, ssl, ftp, gopher and wais.
-
-BIO_set_conn_ip() sets the IP address to B<ip> using binary form,
-that is four bytes specifying the IP address in big endian form.
+fails a standard table of port names will be used. This internal
+list is http, telnet, socks, https, ssl, ftp, and gopher.
-BIO_set_conn_int_port() sets the port using B<port>. B<port> should
-be of type (int *).
+BIO_set_conn_address() sets the address and port information using
+a BIO_ADDR(3ssl).
BIO_get_conn_hostname() returns the hostname of the connect BIO or
-NULL if the BIO is initialised but no hostname is set.
+NULL if the BIO is initialized but no hostname is set.
This return value is an internal pointer which should not be modified.
BIO_get_conn_port() returns the port as a string.
+This return value is an internal pointer which should not be modified.
-BIO_get_conn_ip() returns the IP address in binary form.
-
-BIO_get_conn_int_port() returns the host name as an int.
+BIO_get_conn_address() returns the address information as a BIO_ADDR.
+This return value is an internal pointer which should not be modified.
BIO_set_nbio() sets the non blocking I/O flag to B<n>. If B<n> is
zero then blocking I/O is set. If B<n> is 1 then non blocking I/O
-is set.
+is set. Blocking I/O is the default. The call to BIO_set_nbio()
+should be made before the connection is established because
+non blocking I/O is set during the connect process.
+
+BIO_new_connect() combines BIO_new() and BIO_set_conn_hostname() into
+a single call: that is it creates a new connect BIO with B<name>.
BIO_do_connect() attempts to connect the supplied BIO. It returns 1
if the connection was established successfully. A zero or negative
call BIO_should_retry() should be used for non blocking connect BIOs
to determine if the call should be retried.
-
=head1 NOTES
If blocking I/O is set then a non positive return value from any
will normally mean that the connection was closed.
If the port name is supplied as part of the host name then this will
-override any value set with BIO_set_conn_port().
+override any value set with 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 ':'
+character in the passed hostname and either indicating an error or
+truncating the string at that point.
The values returned by BIO_get_conn_hostname(), BIO_get_conn_port(),
BIO_get_conn_ip() and 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.
-Applications do not have to call BIO_do_connect() but can do so to
-separate the connection process from other I/O processing.
+Applications do not have to call BIO_do_connect() but may wish to do
+so to separate the connection process from other I/O processing.
If non blocking I/O is set then retries will be requested as appropriate.
possible for BIO_should_io_special() to be true during the initial
connection process with the reason BIO_RR_CONNECT. If this is returned
then this is an indication that a connection attempt would block,
-the application should then take appropiate action to wait until
+the application should then take appropriate action to wait until
the underlying socket has connected and retry the call.
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip(),
+BIO_set_conn_int_port(), BIO_get_conn_hostname(), BIO_get_conn_port(),
+BIO_get_conn_ip(), BIO_get_conn_int_port(), BIO_set_nbio() and
+BIO_do_connect() are macros.
+
=head1 RETURN VALUES
BIO_s_connect() returns the connect BIO method.
BIO_get_fd() returns the socket or -1 if the BIO has not
-been initialised.
+been initialized.
+
+BIO_set_conn_hostname(), BIO_set_conn_port(), BIO_set_conn_ip() and
+BIO_set_conn_int_port() always return 1.
+
+BIO_get_conn_hostname() returns the connected hostname or NULL is
+none was set.
+
+BIO_get_conn_port() returns a string representing the connected
+port or NULL if not set.
+
+BIO_get_conn_ip() returns a pointer to the connected IP address in
+binary form or all zeros if not set.
-=head1 EXAMPLES
+BIO_get_conn_int_port() returns the connected port or 0 if none was
+set.
+
+BIO_set_nbio() always returns 1.
+
+BIO_do_connect() returns 1 if the connection was successfully
+established and 0 or -1 if the connection failed.
+
+=head1 EXAMPLE
+
+This is example connects to a webserver on the local host and attempts
+to retrieve a page and copy the result to standard output.
+
+
+ BIO *cbio, *out;
+ int len;
+ char tmpbuf[1024];
+
+ 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\n");
+ ERR_print_errors_fp(stderr);
+ exit(1);
+ }
+ BIO_puts(cbio, "GET / HTTP/1.0\n\n");
+ for ( ; ; ) {
+ len = BIO_read(cbio, tmpbuf, 1024);
+ if(len <= 0)
+ break;
+ BIO_write(out, tmpbuf, len);
+ }
+ BIO_free(cbio);
+ BIO_free(out);
-TBA
=head1 SEE ALSO
-TBA
+L<BIO_ADDR(3)>
+
+=head1 COPYRIGHT
+
+Copyright 2000-2016 The OpenSSL Project Authors. All Rights Reserved.
+
+Licensed under the OpenSSL license (the "License"). You may not use
+this file except in compliance with the License. You can obtain a copy
+in the file LICENSE in the source distribution or at
+L<https://www.openssl.org/source/license.html>.
+
+=cut
projects / openssl.git / blobdiff