You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
195 lines
6.8 KiB
195 lines
6.8 KiB
=pod |
|
|
|
=head1 NAME |
|
|
|
BIO_s_accept, BIO_set_accept_port, BIO_get_accept_port, |
|
BIO_set_nbio_accept, BIO_set_accept_bios, BIO_set_bind_mode, |
|
BIO_get_bind_mode, BIO_do_accept - accept BIO |
|
|
|
=head1 SYNOPSIS |
|
|
|
#include <openssl/bio.h> |
|
|
|
BIO_METHOD *BIO_s_accept(void); |
|
|
|
long BIO_set_accept_port(BIO *b, char *name); |
|
char *BIO_get_accept_port(BIO *b); |
|
|
|
BIO *BIO_new_accept(char *host_port); |
|
|
|
long BIO_set_nbio_accept(BIO *b, int n); |
|
long BIO_set_accept_bios(BIO *b, char *bio); |
|
|
|
long BIO_set_bind_mode(BIO *b, long mode); |
|
long BIO_get_bind_mode(BIO *b, long dummy); |
|
|
|
#define BIO_BIND_NORMAL 0 |
|
#define BIO_BIND_REUSEADDR_IF_UNUSED 1 |
|
#define BIO_BIND_REUSEADDR 2 |
|
|
|
int BIO_do_accept(BIO *b); |
|
|
|
=head1 DESCRIPTION |
|
|
|
BIO_s_accept() returns the accept BIO method. This is a wrapper |
|
round the platform's TCP/IP socket accept routines. |
|
|
|
Using accept BIOs, TCP/IP connections can be accepted 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 an accept BIO will perform I/O |
|
on the underlying connection. If no connection is established |
|
and the port (see below) is set up properly then the BIO |
|
waits for an incoming connection. |
|
|
|
Accept BIOs support BIO_puts() but not BIO_gets(). |
|
|
|
If the close flag is set on an accept BIO then any active |
|
connection on that chain is shutdown and the socket closed when |
|
the BIO is freed. |
|
|
|
Calling BIO_reset() on a accept BIO will close any active |
|
connection and reset the BIO into a state where it awaits another |
|
incoming connection. |
|
|
|
BIO_get_fd() and BIO_set_fd() can be called to retrieve or set |
|
the accept socket. See L<BIO_s_fd(3)|BIO_s_fd(3)> |
|
|
|
BIO_set_accept_port() uses the string B<name> to set the accept |
|
port. The port is represented as a string of the form "host:port", |
|
where "host" is the interface to use and "port" is the port. |
|
The host can be can be "*" which is interpreted as meaning |
|
any interface; "port" has the same syntax |
|
as the port specified in BIO_set_conn_port() for connect BIOs, |
|
that is it can be a numerical port string or a string to lookup |
|
using getservbyname() and a string table. |
|
|
|
BIO_new_accept() combines BIO_new() and BIO_set_accept_port() into |
|
a single call: that is it creates a new accept BIO with port |
|
B<host_port>. |
|
|
|
BIO_set_nbio_accept() sets the accept socket to blocking mode |
|
(the default) if B<n> is 0 or non blocking mode if B<n> is 1. |
|
|
|
BIO_set_accept_bios() can be used to set a chain of BIOs which |
|
will be duplicated and prepended to the chain when an incoming |
|
connection is received. This is useful if, for example, a |
|
buffering or SSL BIO is required for each connection. The |
|
chain of BIOs must not be freed after this call, they will |
|
be automatically freed when the accept BIO is freed. |
|
|
|
BIO_set_bind_mode() and BIO_get_bind_mode() set and retrieve |
|
the current bind mode. If BIO_BIND_NORMAL (the default) is set |
|
then another socket cannot be bound to the same port. If |
|
BIO_BIND_REUSEADDR is set then other sockets can bind to the |
|
same port. If BIO_BIND_REUSEADDR_IF_UNUSED is set then and |
|
attempt is first made to use BIO_BIN_NORMAL, if this fails |
|
and the port is not in use then a second attempt is made |
|
using BIO_BIND_REUSEADDR. |
|
|
|
BIO_do_accept() serves two functions. When it is first |
|
called, after the accept BIO has been setup, it will attempt |
|
to create the accept socket and bind an address to it. Second |
|
and subsequent calls to BIO_do_accept() will await an incoming |
|
connection, or request a retry in non blocking mode. |
|
|
|
=head1 NOTES |
|
|
|
When an accept BIO is at the end of a chain it will await an |
|
incoming connection before processing I/O calls. When an accept |
|
BIO is not at then end of a chain it passes I/O calls to the next |
|
BIO in the chain. |
|
|
|
When a connection is established a new socket BIO is created for |
|
the connection and appended to the chain. That is the chain is now |
|
accept->socket. This effectively means that attempting I/O on |
|
an initial accept socket will await an incoming connection then |
|
perform I/O on it. |
|
|
|
If any additional BIOs have been set using BIO_set_accept_bios() |
|
then they are placed between the socket and the accept BIO, |
|
that is the chain will be accept->otherbios->socket. |
|
|
|
If a server wishes to process multiple connections (as is normally |
|
the case) then the accept BIO must be made available for further |
|
incoming connections. This can be done by waiting for a connection and |
|
then calling: |
|
|
|
connection = BIO_pop(accept); |
|
|
|
After this call B<connection> will contain a BIO for the recently |
|
established connection and B<accept> will now be a single BIO |
|
again which can be used to await further incoming connections. |
|
If no further connections will be accepted the B<accept> can |
|
be freed using BIO_free(). |
|
|
|
If only a single connection will be processed it is possible to |
|
perform I/O using the accept BIO itself. This is often undesirable |
|
however because the accept BIO will still accept additional incoming |
|
connections. This can be resolved by using BIO_pop() (see above) |
|
and freeing up the accept BIO after the initial connection. |
|
|
|
If the underlying accept socket is non-blocking and BIO_do_accept() is |
|
called to await an incoming connection it is possible for |
|
BIO_should_io_special() with the reason BIO_RR_ACCEPT. If this happens |
|
then it is an indication that an accept attempt would block: the application |
|
should take appropriate action to wait until the underlying socket has |
|
accepted a connection and retry the call. |
|
|
|
BIO_set_accept_port(), BIO_get_accept_port(), BIO_set_nbio_accept(), |
|
BIO_set_accept_bios(), BIO_set_bind_mode(), BIO_get_bind_mode() and |
|
BIO_do_accept() are macros. |
|
|
|
=head1 RETURN VALUES |
|
|
|
TBA |
|
|
|
=head1 EXAMPLE |
|
|
|
This example accepts two connections on port 4444, sends messages |
|
down each and finally closes both down. |
|
|
|
BIO *abio, *cbio, *cbio2; |
|
ERR_load_crypto_strings(); |
|
abio = BIO_new_accept("4444"); |
|
|
|
/* First call to BIO_accept() sets up accept BIO */ |
|
if(BIO_do_accept(abio) <= 0) { |
|
fprintf(stderr, "Error setting up accept\n"); |
|
ERR_print_errors_fp(stderr); |
|
exit(0); |
|
} |
|
|
|
/* Wait for incoming connection */ |
|
if(BIO_do_accept(abio) <= 0) { |
|
fprintf(stderr, "Error accepting connection\n"); |
|
ERR_print_errors_fp(stderr); |
|
exit(0); |
|
} |
|
fprintf(stderr, "Connection 1 established\n"); |
|
/* Retrieve BIO for connection */ |
|
cbio = BIO_pop(abio); |
|
BIO_puts(cbio, "Connection 1: Sending out Data on initial connection\n"); |
|
fprintf(stderr, "Sent out data on connection 1\n"); |
|
/* Wait for another connection */ |
|
if(BIO_do_accept(abio) <= 0) { |
|
fprintf(stderr, "Error accepting connection\n"); |
|
ERR_print_errors_fp(stderr); |
|
exit(0); |
|
} |
|
fprintf(stderr, "Connection 2 established\n"); |
|
/* Close accept BIO to refuse further connections */ |
|
cbio2 = BIO_pop(abio); |
|
BIO_free(abio); |
|
BIO_puts(cbio2, "Connection 2: Sending out Data on second\n"); |
|
fprintf(stderr, "Sent out data on connection 2\n"); |
|
|
|
BIO_puts(cbio, "Connection 1: Second connection established\n"); |
|
/* Close the two established connections */ |
|
BIO_free(cbio); |
|
BIO_free(cbio2); |
|
|
|
=head1 SEE ALSO |
|
|
|
TBA
|
|
|