diff options
author | Richard Levitte <levitte@openssl.org> | 2016-02-02 21:04:54 +0100 |
---|---|---|
committer | Richard Levitte <levitte@openssl.org> | 2016-02-03 19:38:07 +0100 |
commit | d33b215b331116e50947ca7e75d210e1db39b78d (patch) | |
tree | e6ff0dbddd1ad7a894aa69712f916b13991789d7 /doc | |
parent | 83be2778fe11ede4cd065a136c686fe664c212a2 (diff) | |
download | openssl-d33b215b331116e50947ca7e75d210e1db39b78d.tar.gz |
Refactoring BIO: new socket-handling functions, deprecate older ones
Added functions:
BIO_socket
BIO_connect
BIO_listen
BIO_accept_ex
BIO_closesocket
BIO_sock_info
These get deprecated:
BIO_gethostbyname
BIO_get_port
BIO_get_host_ip
BIO_get_accept_socket
BIO_accept
Reviewed-by: Kurt Roeckx <kurt@openssl.org>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/crypto/BIO_connect.pod | 101 |
1 files changed, 101 insertions, 0 deletions
diff --git a/doc/crypto/BIO_connect.pod b/doc/crypto/BIO_connect.pod new file mode 100644 index 0000000000..4edb8baf7c --- /dev/null +++ b/doc/crypto/BIO_connect.pod @@ -0,0 +1,101 @@ +=pod + +=head1 NAME + +BIO_socket, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO +socket communication setup routines + +=head1 SYNOPSIS + + #include <openssl/bio.h> + + int BIO_socket(int domain, int socktype, int protocol, int options); + int BIO_connect(int sock, const BIO_ADDR *addr, int options); + int BIO_listen(int sock, const BIO_ADDR *addr, int options); + int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options); + int BIO_closesocket(int sock); + +=head1 DESCRIPTION + +BIO_socket() creates a socket in the domain B<domain>, of type +B<socktype> and B<protocol>. Socket B<options> are currently unused, +but is present for future use. + +BIO_connect() connects B<sock> to the address and service given by +B<addr>. Connection B<options> may be zero or any combination of +B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>. +The flags are described in L</FLAGS> below. + +BIO_listen() has B<sock> start listening on the address and service +given by B<addr>. Connection B<options> may be zero or any +combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>, +B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>. +The flags are described in L</FLAGS> below. + +BIO_accept_ex() waits for an incoming connections on the given +socket B<accept_sock>. When it gets a connection, the address and +port of the peer gets stored in B<peer> if that one is non-NULL. +Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied +on the accepted socket. The flags are described in L</FLAGS> below. + +BIO_closesocket() closes B<sock>. + +=head1 FLAGS + +=over 4 + +=item BIO_SOCK_KEEPALIVE + +Enables regular sending of keep-alive messages. + +=item BIO_SOCK_NONBLOCK + +Sets the socket to non-blocking mode. + +=item BIO_SOCK_NODELAY + +Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With +this set, any data will be sent as soon as possible instead of being +buffered until there's enough for the socket to send out in one go. + +=item BIO_SOCK_REUSEADDR + +Try to reuse the address and port combination for a recently closed +port. + +=item BIO_SOCK_V6_ONLY + +When creating an IPv6 socket, make it only listen for IPv6 addresses +and not IPv4 addresses mapped to IPv6. + +=back + +These flags are bit flags, so they are to be combined with the +C<|> operator, for example: + + BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK); + +=head1 RETURN VALUES + +BIO_socket() returns the socket number on success or B<INVALID_SOCKET> +(-1) on error. When an error has occured, the OpenSSL error stack +will hold the error data and errno has the system error. + +BIO_connect() and BIO_listen() return 1 on success or 0 on error. +When an error has occured, the OpenSSL error stack will hold the error +data and errno has the system error. + +BIO_accept_ex() returns the accepted socket on success or +B<INVALID_SOCKET> (-1) on error. When an error has occured, the +OpenSSL error stack will hold the error data and errno has the system +error. + +=head1 HISTORY + +BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(), +BIO_get_accept_socket() and BIO_accept() are deprecated since OpenSSL +1.1. Use the functions described above instead. + +=head1 SEE ALSO + +L<BIO_ADDR(3)> |