Add manpages

Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Matt Caswell <matt@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/21715)

diff --git a/doc/man3/BIO_s_connect.pod b/doc/man3/BIO_s_connect.pod
index 4d07994c23653f57e4bf611dec52f2a7313481af..0c1106c5234e9d08c5b3d0030c975c85c6121adc 100644 (file)
--- a/doc/man3/BIO_s_connect.pod
+++ b/doc/man3/BIO_s_connect.pod
@@ -7,7 +7,8 @@ BIO_set_conn_hostname, BIO_set_conn_port,
 BIO_set_conn_address, BIO_set_conn_ip_family,
 BIO_get_conn_hostname, BIO_get_conn_port,
 BIO_get_conn_address, BIO_get_conn_ip_family,
-BIO_set_nbio, BIO_do_connect - connect BIO
+BIO_set_nbio, BIO_set_sock_type, BIO_get_sock_type, BIO_get_dgram_bio,
+BIO_do_connect - connect BIO
 
 =head1 SYNOPSIS
 
@@ -28,6 +29,10 @@ BIO_set_nbio, BIO_do_connect - connect BIO
 
  long BIO_set_nbio(BIO *b, long n);
 
+ int BIO_set_sock_type(BIO *b, int sock_type);
+ int BIO_get_sock_type(BIO *b);
+ int BIO_get_dgram_bio(BIO *B, BIO **dgram_bio);
+
  long BIO_do_connect(BIO *b);
 
 =head1 DESCRIPTION
@@ -101,6 +106,17 @@ The call BIO_should_retry() should be used for non blocking connect BIOs
 to determine if the call should be retried.
 If a connection has already been established this call has no effect.
 
+BIO_set_sock_type() can be used to set a socket type value as would be passed in
+a call to socket(2). The only currently supported values are B<SOCK_STREAM> (the
+default) and B<SOCK_DGRAM>. If B<SOCK_DGRAM> is configured, the connection
+created is a UDP datagram socket handled via L<BIO_s_datagram(3)>.
+I/O calls such as L<BIO_read(3)> and L<BIO_write(3)> are forwarded transparently
+to an internal L<BIO_s_datagram(3)> instance. The created L<BIO_s_datagram(3)>
+instance can be retrieved using BIO_get_dgram_bio() if desired, which writes
+a pointer to the L<BIO_s_datagram(3)> instance to I<*dgram_bio>.
+
+BIO_get_sock_type() retrieves the value set using BIO_set_sock_type().
+
 =head1 NOTES
 
 If blocking I/O is set then a non positive return value from any
@@ -161,6 +177,12 @@ BIO_set_nbio() returns 1 or <=0 if an error occurs.
 BIO_do_connect() returns 1 if the connection was successfully
 established and <=0 if the connection failed.
 
+BIO_set_sock_type() returns 1 on success or 0 on failure.
+
+BIO_get_sock_type() returns a socket type or 0 if the call is not supported.
+
+BIO_get_dgram_bio() returns 1 on success or 0 on failure.
+
 =head1 EXAMPLES
 
 This is example connects to a webserver on the local host and attempts

diff --git a/doc/man3/BIO_s_datagram.pod b/doc/man3/BIO_s_datagram.pod
index 3ff24cc55127cc605b26e284b801b0d236f15c24..3045536200fe75d9d4978cd308ca82d0cc34f5cf 100644 (file)
--- a/doc/man3/BIO_s_datagram.pod
+++ b/doc/man3/BIO_s_datagram.pod
@@ -9,6 +9,7 @@ BIO_dgram_recv_timedout,
 BIO_dgram_send_timedout,
 BIO_dgram_get_peer,
 BIO_dgram_set_peer,
+BIO_dgram_detect_peer_addr,
 BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics
 
 =head1 SYNOPSIS
@@ -25,6 +26,7 @@ BIO_dgram_get_mtu_overhead - Network BIO with datagram semantics
  int BIO_dgram_get_peer(BIO *bio, BIO_ADDR *peer);
  int BIO_dgram_set_peer(BIO *bio, const BIO_ADDR *peer);
  int BIO_dgram_get_mtu_overhead(BIO *bio);
+ int BIO_dgram_detect_peer_addr(BIO *bio, BIO_ADDR *peer);
 
 =head1 DESCRIPTION
 
@@ -144,6 +146,15 @@ hazardous when used with unconnected network sockets; see above.
 This does not affect the operation of L<BIO_sendmmsg(3)>.
 L<BIO_recvmmsg(3)> does not affect the value set by BIO_dgram_set_peer().
 
+=item BIO_dgram_detect_peer_addr (BIO_CTRL_DGRAM_DETECT_PEER_ADDR)
+
+This is similar to BIO_dgram_get_peer() except that if the peer address has not
+been set on the BIO object, an OS call such as getpeername(2) will be attempted
+to try and autodetect the peer address to which the underlying socket is
+connected. Other BIOs may also implement this control if they are capable of
+sensing a peer address, without necessarily also implementing
+BIO_dgram_set_peer() and BIO_dgram_get_peer().
+
 =item BIO_dgram_recv_timeout (BIO_CTRL_DGRAM_GET_RECV_TIMER_EXP)
 
 Returns 1 if the last I/O operation performed on the BIO (for example, via a
@@ -231,8 +242,12 @@ BIO_s_datagram() returns a BIO method.
 
 BIO_new_dgram() returns a BIO on success and NULL on failure.
 
-BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected(),
-BIO_dgram_get_peer(), BIO_dgram_set_peer() return 1 on success and 0 on failure.
+BIO_ctrl_dgram_connect(), BIO_ctrl_set_connected() and BIO_dgram_set_peer()
+return 1 on success and 0 on failure.
+
+BIO_dgram_get_peer() and BIO_dgram_detect_peer_addr() return 0 on failure and
+the number of bytes for the outputted address representation (a positive value)
+on success.
 
 BIO_dgram_recv_timedout() and BIO_dgram_send_timedout() return 0 or 1 depending
 on the circumstance; see discussion above.

diff --git a/util/other.syms b/util/other.syms
index ea48770ea0445b3fe5c5c1bd3d4932f3c32200b4..cd1f73468dbd0d0d55ee398d28d1b154fbc00d28 100644 (file)
--- a/util/other.syms
+++ b/util/other.syms
@@ -168,6 +168,10 @@ BIO_dgram_get_peer                      define
 BIO_dgram_set_peer                      define
 BIO_dgram_recv_timedout                 define
 BIO_dgram_send_timedout                 define
+BIO_dgram_detect_peer_addr              define
+BIO_get_dgram_bio                       define
+BIO_get_sock_type                       define
+BIO_set_sock_type                       define
 BIO_do_accept                           define
 BIO_do_connect                          define
 BIO_do_handshake                        define