| 1 | =pod
|
|---|
| 2 |
|
|---|
| 3 | =head1 NAME
|
|---|
| 4 |
|
|---|
| 5 | BIO_socket, BIO_bind, BIO_connect, BIO_listen, BIO_accept_ex, BIO_closesocket - BIO
|
|---|
| 6 | socket communication setup routines
|
|---|
| 7 |
|
|---|
| 8 | =head1 SYNOPSIS
|
|---|
| 9 |
|
|---|
| 10 | #include <openssl/bio.h>
|
|---|
| 11 |
|
|---|
| 12 | int BIO_socket(int domain, int socktype, int protocol, int options);
|
|---|
| 13 | int BIO_bind(int sock, const BIO_ADDR *addr, int options);
|
|---|
| 14 | int BIO_connect(int sock, const BIO_ADDR *addr, int options);
|
|---|
| 15 | int BIO_listen(int sock, const BIO_ADDR *addr, int options);
|
|---|
| 16 | int BIO_accept_ex(int accept_sock, BIO_ADDR *peer, int options);
|
|---|
| 17 | int BIO_closesocket(int sock);
|
|---|
| 18 |
|
|---|
| 19 | =head1 DESCRIPTION
|
|---|
| 20 |
|
|---|
| 21 | BIO_socket() creates a socket in the domain B<domain>, of type
|
|---|
| 22 | B<socktype> and B<protocol>. Socket B<options> are currently unused,
|
|---|
| 23 | but is present for future use.
|
|---|
| 24 |
|
|---|
| 25 | BIO_bind() binds the source address and service to a socket and
|
|---|
| 26 | may be useful before calling BIO_connect(). The options may include
|
|---|
| 27 | B<BIO_SOCK_REUSEADDR>, which is described in L</FLAGS> below.
|
|---|
| 28 |
|
|---|
| 29 | BIO_connect() connects B<sock> to the address and service given by
|
|---|
| 30 | B<addr>. Connection B<options> may be zero or any combination of
|
|---|
| 31 | B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK> and B<BIO_SOCK_NODELAY>.
|
|---|
| 32 | The flags are described in L</FLAGS> below.
|
|---|
| 33 |
|
|---|
| 34 | BIO_listen() has B<sock> start listening on the address and service
|
|---|
| 35 | given by B<addr>. Connection B<options> may be zero or any
|
|---|
| 36 | combination of B<BIO_SOCK_KEEPALIVE>, B<BIO_SOCK_NONBLOCK>,
|
|---|
| 37 | B<BIO_SOCK_NODELAY>, B<BIO_SOCK_REUSEADDR> and B<BIO_SOCK_V6_ONLY>.
|
|---|
| 38 | The flags are described in L</FLAGS> below.
|
|---|
| 39 |
|
|---|
| 40 | BIO_accept_ex() waits for an incoming connections on the given
|
|---|
| 41 | socket B<accept_sock>. When it gets a connection, the address and
|
|---|
| 42 | port of the peer gets stored in B<peer> if that one is non-NULL.
|
|---|
| 43 | Accept B<options> may be zero or B<BIO_SOCK_NONBLOCK>, and is applied
|
|---|
| 44 | on the accepted socket. The flags are described in L</FLAGS> below.
|
|---|
| 45 |
|
|---|
| 46 | BIO_closesocket() closes B<sock>.
|
|---|
| 47 |
|
|---|
| 48 | =head1 FLAGS
|
|---|
| 49 |
|
|---|
| 50 | =over 4
|
|---|
| 51 |
|
|---|
| 52 | =item BIO_SOCK_KEEPALIVE
|
|---|
| 53 |
|
|---|
| 54 | Enables regular sending of keep-alive messages.
|
|---|
| 55 |
|
|---|
| 56 | =item BIO_SOCK_NONBLOCK
|
|---|
| 57 |
|
|---|
| 58 | Sets the socket to nonblocking mode.
|
|---|
| 59 |
|
|---|
| 60 | =item BIO_SOCK_NODELAY
|
|---|
| 61 |
|
|---|
| 62 | Corresponds to B<TCP_NODELAY>, and disables the Nagle algorithm. With
|
|---|
| 63 | this set, any data will be sent as soon as possible instead of being
|
|---|
| 64 | buffered until there's enough for the socket to send out in one go.
|
|---|
| 65 |
|
|---|
| 66 | =item BIO_SOCK_REUSEADDR
|
|---|
| 67 |
|
|---|
| 68 | Try to reuse the address and port combination for a recently closed
|
|---|
| 69 | port.
|
|---|
| 70 |
|
|---|
| 71 | =item BIO_SOCK_V6_ONLY
|
|---|
| 72 |
|
|---|
| 73 | When creating an IPv6 socket, make it only listen for IPv6 addresses
|
|---|
| 74 | and not IPv4 addresses mapped to IPv6.
|
|---|
| 75 |
|
|---|
| 76 | =back
|
|---|
| 77 |
|
|---|
| 78 | These flags are bit flags, so they are to be combined with the
|
|---|
| 79 | C<|> operator, for example:
|
|---|
| 80 |
|
|---|
| 81 | BIO_connect(sock, addr, BIO_SOCK_KEEPALIVE | BIO_SOCK_NONBLOCK);
|
|---|
| 82 |
|
|---|
| 83 | =head1 RETURN VALUES
|
|---|
| 84 |
|
|---|
| 85 | BIO_socket() returns the socket number on success or B<INVALID_SOCKET>
|
|---|
| 86 | (-1) on error. When an error has occurred, the OpenSSL error stack
|
|---|
| 87 | will hold the error data and errno has the system error.
|
|---|
| 88 |
|
|---|
| 89 | BIO_bind(), BIO_connect() and BIO_listen() return 1 on success or 0 on error.
|
|---|
| 90 | When an error has occurred, the OpenSSL error stack will hold the error
|
|---|
| 91 | data and errno has the system error.
|
|---|
| 92 |
|
|---|
| 93 | BIO_accept_ex() returns the accepted socket on success or
|
|---|
| 94 | B<INVALID_SOCKET> (-1) on error. When an error has occurred, the
|
|---|
| 95 | OpenSSL error stack will hold the error data and errno has the system
|
|---|
| 96 | error.
|
|---|
| 97 |
|
|---|
| 98 | =head1 SEE ALSO
|
|---|
| 99 |
|
|---|
| 100 | L<BIO_ADDR(3)>
|
|---|
| 101 |
|
|---|
| 102 | =head1 HISTORY
|
|---|
| 103 |
|
|---|
| 104 | BIO_gethostname(), BIO_get_port(), BIO_get_host_ip(),
|
|---|
| 105 | BIO_get_accept_socket() and BIO_accept() were deprecated in OpenSSL 1.1.0.
|
|---|
| 106 | Use the functions described above instead.
|
|---|
| 107 |
|
|---|
| 108 | =head1 COPYRIGHT
|
|---|
| 109 |
|
|---|
| 110 | Copyright 2016-2020 The OpenSSL Project Authors. All Rights Reserved.
|
|---|
| 111 |
|
|---|
| 112 | Licensed under the OpenSSL license (the "License"). You may not use
|
|---|
| 113 | this file except in compliance with the License. You can obtain a copy
|
|---|
| 114 | in the file LICENSE in the source distribution or at
|
|---|
| 115 | L<https://www.openssl.org/source/license.html>.
|
|---|
| 116 |
|
|---|
| 117 | =cut
|
|---|
