From: Matt Caswell <matt@openssl.org>
Date: Tue, 26 Nov 2024 12:46:00 +0000 (+0000)
Subject: Add documentation for BIO_dgram_set0_local_addr()
X-Git-Tag: openssl-3.5.0-alpha1~316
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=6d1646c66ed31f90c88bf7961a83d8650bc31fa1;p=thirdparty%2Fopenssl.git

Add documentation for BIO_dgram_set0_local_addr()

Reviewed-by: Tim Hudson <tjh@openssl.org>
Reviewed-by: Tomas Mraz <tomas@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
Reviewed-by: Saša Nedvědický <sashan@openssl.org>
(Merged from https://github.com/openssl/openssl/pull/26066)
---

diff --git a/doc/man3/BIO_s_dgram_pair.pod b/doc/man3/BIO_s_dgram_pair.pod
index bcd70de48c3..5c750794353 100644
--- a/doc/man3/BIO_s_dgram_pair.pod
+++ b/doc/man3/BIO_s_dgram_pair.pod
@@ -4,7 +4,8 @@
 
 BIO_s_dgram_pair, BIO_new_bio_dgram_pair, BIO_dgram_set_no_trunc,
 BIO_dgram_get_no_trunc, BIO_dgram_get_effective_caps, BIO_dgram_get_caps,
-BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu - datagram pair BIO
+BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu,
+BIO_dgram_set0_local_addr - datagram pair BIO
 
 =head1 SYNOPSIS
 
@@ -21,6 +22,7 @@ BIO_dgram_set_caps, BIO_dgram_set_mtu, BIO_dgram_get_mtu - datagram pair BIO
  int BIO_dgram_set_caps(BIO *bio, uint32_t caps);
  int BIO_dgram_set_mtu(BIO *bio, unsigned int mtu);
  unsigned int BIO_dgram_get_mtu(BIO *bio);
+ int BIO_dgram_set0_local_addr(BIO *bio, BIO_ADDR *addr);
 
 =head1 DESCRIPTION
 
@@ -102,6 +104,14 @@ pair (except for BIO_get_write_guarantee(); see above) but may be used by other
 code to determine a requested MTU. When a BIO datagram pair BIO is created, the
 MTU is set to an unspecified but valid value.
 
+BIO_dgram_set0_local_addr() can be used to set the local BIO_ADDR to be used
+when sending a datagram via a BIO datagram pair. This becomes the peer address
+when receiving on the other half of the pair. If the BIO is used in a call to
+L<BIO_sendmmsg(3)> and a local address is explicitly specified, then the
+explicitly specified local address takes precedence. The reference to the
+BIO_ADDR is passed to the BIO by this call and will be freed automatically when
+the BIO is freed.
+
 L<BIO_flush(3)> is a no-op.
 
 =head1 NOTES
@@ -206,6 +216,8 @@ capabilities are supported.
 BIO_dgram_get_mtu() returns the MTU value configured on the BIO, or zero if the
 operation is not supported.
 
+BIO_dgram_set0_local_addr() returns 1 on success and <= 0 otherwise.
+
 =head1 SEE ALSO
 
 L<BIO_s_bio(3)>, L<bio(7)>
diff --git a/util/other.syms b/util/other.syms
index 6a95f583f5a..f619a5501dd 100644
--- a/util/other.syms
+++ b/util/other.syms
@@ -183,6 +183,7 @@ BIO_ctrl_set_connected                  define
 BIO_dgram_get_mtu_overhead              define
 BIO_dgram_get_peer                      define
 BIO_dgram_set_peer                      define
+BIO_dgram_set0_local_addr               define
 BIO_dgram_recv_timedout                 define
 BIO_dgram_send_timedout                 define
 BIO_dgram_detect_peer_addr              define