7fcc8326e3
indent there, especially since the pod2* scripts will regard that as preformated text. In one case, indent a code section one step.
132 lines
4.7 KiB
Plaintext
132 lines
4.7 KiB
Plaintext
=pod
|
|
|
|
=head1 NAME
|
|
|
|
BIO_s_connect - connect BIO
|
|
|
|
=head1 SYNOPSIS
|
|
|
|
#include <openssl/bio.h>
|
|
|
|
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)
|
|
|
|
#define BIO_set_nbio(b,n) BIO_ctrl(b,BIO_C_SET_NBIO,(n),NULL)
|
|
|
|
#define BIO_do_connect(b) BIO_do_handshake(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
|
|
transferred using only BIO routines. In this way any platform
|
|
specific operations are hidden by the BIO abstraction.
|
|
|
|
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.
|
|
|
|
Connect BIOs support BIO_puts() but not BIO_gets().
|
|
|
|
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.
|
|
|
|
Calling BIO_reset() 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.
|
|
|
|
BIO_get_fd() places the underlying socket in B<c> if it is not NULL,
|
|
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_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.
|
|
|
|
BIO_set_conn_int_port() sets the port using B<port>. B<port> should
|
|
be of type (int *).
|
|
|
|
BIO_get_conn_hostname() returns the hostname of the connect BIO or
|
|
NULL if the BIO is initialised 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.
|
|
|
|
BIO_get_conn_ip() returns the IP address in binary form.
|
|
|
|
BIO_get_conn_int_port() returns the host name as an int.
|
|
|
|
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.
|
|
|
|
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 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
|
|
I/O call is caused by an error condition, although a zero return
|
|
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().
|
|
|
|
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.
|
|
|
|
If non blocking I/O is set then retries will be requested as appropriate.
|
|
|
|
It addition to BIO_should_read() and BIO_should_write() it is also
|
|
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 underlying socket has connected and retry the call.
|
|
|
|
=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.
|
|
|
|
=head1 EXAMPLES
|
|
|
|
TBA
|
|
|
|
=head1 SEE ALSO
|
|
|
|
TBA
|