From bbb0cceb7a1926daad6bb5860d90e05caaaf7989 Mon Sep 17 00:00:00 2001
From: Kittywhiskers Van Gogh <63189531+kwvg@users.noreply.github.com>
Date: Tue, 28 Jun 2022 13:27:57 +0100
Subject: [PATCH] merge bitcoin#25493: document code in compat.h

---
 src/Makefile.am                        |  2 +-
 src/bitcoin-cli.cpp                    |  2 +-
 src/bitcoin-tx.cpp                     |  2 +-
 src/bitcoin-wallet.cpp                 |  2 +-
 src/bitcoind.cpp                       |  2 +-
 src/{ => compat}/compat.h              | 52 +++++++++++++++-----------
 src/i2p.cpp                            |  2 +-
 src/i2p.h                              |  2 +-
 src/mapport.cpp                        |  2 +-
 src/net.cpp                            |  2 +-
 src/net.h                              |  2 +-
 src/netaddress.h                       |  2 +-
 src/netbase.cpp                        |  2 +-
 src/netbase.h                          |  2 +-
 src/qt/main.cpp                        |  2 +-
 src/random.cpp                         |  2 +-
 src/randomenv.cpp                      |  2 +-
 src/stats/rawsender.h                  |  2 +-
 src/test/fuzz/util.h                   |  2 +-
 src/test/fuzz/util/net.cpp             |  2 +-
 src/test/net_peer_connection_tests.cpp |  2 +-
 src/test/net_tests.cpp                 |  2 +-
 src/test/sock_tests.cpp                |  2 +-
 src/test/util/net.h                    |  2 +-
 src/torcontrol.cpp                     |  2 +-
 src/util/edge.h                        |  2 +-
 src/util/sock.cpp                      |  2 +-
 src/util/sock.h                        |  2 +-
 src/util/system.h                      |  2 +-
 src/util/time.cpp                      |  2 +-
 src/util/time.h                        |  2 +-
 src/wallet/bdb.cpp                     |  1 +
 32 files changed, 61 insertions(+), 52 deletions(-)
 rename src/{ => compat}/compat.h (72%)

diff --git a/src/Makefile.am b/src/Makefile.am
index 7c615cc7dd..3b714b247c 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -163,9 +163,9 @@ BITCOIN_CORE_H = \
   coinjoin/util.h \
   coins.h \
   common/bloom.h \
-  compat.h \
   compat/assumptions.h \
   compat/byteswap.h \
+  compat/compat.h \
   compat/cpuid.h \
   compat/endian.h \
   compressor.h \
diff --git a/src/bitcoin-cli.cpp b/src/bitcoin-cli.cpp
index 045cf0ae76..43790e9ac4 100644
--- a/src/bitcoin-cli.cpp
+++ b/src/bitcoin-cli.cpp
@@ -10,7 +10,7 @@
 
 #include <chainparamsbase.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <compat/stdin.h>
 #include <policy/feerate.h>
 #include <rpc/client.h>
diff --git a/src/bitcoin-tx.cpp b/src/bitcoin-tx.cpp
index 0eb122f086..cb40879f8e 100644
--- a/src/bitcoin-tx.cpp
+++ b/src/bitcoin-tx.cpp
@@ -9,7 +9,7 @@
 #include <chainparams.h>
 #include <clientversion.h>
 #include <coins.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/consensus.h>
 #include <core_io.h>
 #include <key_io.h>
diff --git a/src/bitcoin-wallet.cpp b/src/bitcoin-wallet.cpp
index 8e7c1490fd..4dfb973042 100644
--- a/src/bitcoin-wallet.cpp
+++ b/src/bitcoin-wallet.cpp
@@ -8,7 +8,7 @@
 
 #include <chainparams.h>
 #include <chainparamsbase.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <logging.h>
 #include <util/strencodings.h>
 #include <util/system.h>
diff --git a/src/bitcoind.cpp b/src/bitcoind.cpp
index c16167f412..a3b9910e2d 100644
--- a/src/bitcoind.cpp
+++ b/src/bitcoind.cpp
@@ -10,7 +10,7 @@
 
 #include <chainparams.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <init.h>
 #include <interfaces/chain.h>
 #include <interfaces/init.h>
diff --git a/src/compat.h b/src/compat/compat.h
similarity index 72%
rename from src/compat.h
rename to src/compat/compat.h
index 7940d78103..eeac0805db 100644
--- a/src/compat.h
+++ b/src/compat/compat.h
@@ -3,21 +3,24 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-#ifndef BITCOIN_COMPAT_H
-#define BITCOIN_COMPAT_H
+#ifndef BITCOIN_COMPAT_COMPAT_H
+#define BITCOIN_COMPAT_COMPAT_H
 
 #if defined(HAVE_CONFIG_H)
 #include <config/bitcoin-config.h>
 #endif
 
+// Windows defines FD_SETSIZE to 64 (see _fd_types.h in mingw-w64),
+// which is too small for our usage, but allows us to redefine it safely.
+// We redefine it to be 1024, to match glibc, see typesizes.h.
 #ifdef WIN32
 #ifdef FD_SETSIZE
-#undef FD_SETSIZE // prevent redefinition compiler warning
+#undef FD_SETSIZE
 #endif
-#define FD_SETSIZE 1024 // max number of fds in fd_set
+#define FD_SETSIZE 1024
 #include <winsock2.h>
 #include <ws2tcpip.h>
-#include <stdint.h>
+#include <cstdint>
 #else
 #include <fcntl.h>
 #include <sys/mman.h>
@@ -34,50 +37,55 @@
 #include <unistd.h>
 #endif
 
+// We map Linux / BSD error functions and codes, to the equivalent
+// Windows definitions, and use the WSA* names throughout our code.
+// Note that glibc defines EWOULDBLOCK as EAGAIN (see errno.h).
 #ifndef WIN32
 typedef unsigned int SOCKET;
-#include <errno.h>
+#include <cerrno>
 #define WSAGetLastError()   errno
 #define WSAEINVAL           EINVAL
-#define WSAEALREADY         EALREADY
 #define WSAEWOULDBLOCK      EWOULDBLOCK
 #define WSAEAGAIN           EAGAIN
 #define WSAEMSGSIZE         EMSGSIZE
 #define WSAEINTR            EINTR
 #define WSAEINPROGRESS      EINPROGRESS
 #define WSAEADDRINUSE       EADDRINUSE
-#define WSAENOTSOCK         EBADF
 #define INVALID_SOCKET      (SOCKET)(~0)
 #define SOCKET_ERROR        -1
 #define SD_SEND             SHUT_WR
 #else
-#ifndef WSAEAGAIN
+// WSAEAGAIN doesn't exist on Windows
 #ifdef EAGAIN
 #define WSAEAGAIN EAGAIN
 #else
 #define WSAEAGAIN WSAEWOULDBLOCK
 #endif
 #endif
-#endif
 
+// Windows doesn't define S_IRUSR or S_IWUSR. We define both
+// here, with the same values as glibc (see stat.h).
 #ifdef WIN32
 #ifndef S_IRUSR
 #define S_IRUSR             0400
 #define S_IWUSR             0200
 #endif
-#else
-#define MAX_PATH            1024
-#endif
-#ifdef _MSC_VER
-#if !defined(ssize_t)
-#ifdef _WIN64
-typedef int64_t ssize_t;
-#else
-typedef int32_t ssize_t;
-#endif
-#endif
 #endif
 
+// Windows defines MAX_PATH as it's maximum path length.
+// We define MAX_PATH for use on non-Windows systems.
+#ifndef WIN32
+#define MAX_PATH            1024
+#endif
+
+// ssize_t is POSIX, and not present when using MSVC.
+#ifdef _MSC_VER
+#include <BaseTsd.h>
+typedef SSIZE_T ssize_t;
+#endif
+
+// The type of the option value passed to getsockopt & setsockopt
+// differs between Windows and non-Windows.
 #ifndef WIN32
 typedef void* sockopt_arg_type;
 #else
@@ -128,4 +136,4 @@ bool static inline IsSelectableSocket(const SOCKET& s) {
 #define MSG_DONTWAIT 0
 #endif
 
-#endif // BITCOIN_COMPAT_H
+#endif // BITCOIN_COMPAT_COMPAT_H
diff --git a/src/i2p.cpp b/src/i2p.cpp
index 507bdeab55..8ecb50645f 100644
--- a/src/i2p.cpp
+++ b/src/i2p.cpp
@@ -3,7 +3,7 @@
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 #include <chainparams.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <compat/endian.h>
 #include <crypto/sha256.h>
 #include <fs.h>
diff --git a/src/i2p.h b/src/i2p.h
index f9619de9c5..fc9256160b 100644
--- a/src/i2p.h
+++ b/src/i2p.h
@@ -5,7 +5,7 @@
 #ifndef BITCOIN_I2P_H
 #define BITCOIN_I2P_H
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <fs.h>
 #include <netaddress.h>
 #include <sync.h>
diff --git a/src/mapport.cpp b/src/mapport.cpp
index ecdbcdff12..5a38353070 100644
--- a/src/mapport.cpp
+++ b/src/mapport.cpp
@@ -18,7 +18,7 @@
 #include <util/thread.h>
 
 #ifdef USE_NATPMP
-#include <compat.h>
+#include <compat/compat.h>
 #include <natpmp.h>
 #endif // USE_NATPMP
 
diff --git a/src/net.cpp b/src/net.cpp
index 5f82196c42..9bfb813178 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -15,7 +15,7 @@
 #include <addrman.h>
 #include <banman.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/consensus.h>
 #include <crypto/sha256.h>
 #include <node/eviction.h>
diff --git a/src/net.h b/src/net.h
index 446e687048..524f0a244b 100644
--- a/src/net.h
+++ b/src/net.h
@@ -9,7 +9,7 @@
 #include <bip324.h>
 #include <chainparams.h>
 #include <common/bloom.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/amount.h>
 #include <fs.h>
 #include <crypto/siphash.h>
diff --git a/src/netaddress.h b/src/netaddress.h
index 102de00225..4d53ed9694 100644
--- a/src/netaddress.h
+++ b/src/netaddress.h
@@ -10,7 +10,7 @@
 #endif
 
 #include <attributes.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <crypto/siphash.h>
 #include <prevector.h>
 #include <random.h>
diff --git a/src/netbase.cpp b/src/netbase.cpp
index cf1ba19e65..adaf3fa629 100644
--- a/src/netbase.cpp
+++ b/src/netbase.cpp
@@ -5,7 +5,7 @@
 
 #include <netbase.h>
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <sync.h>
 #include <tinyformat.h>
 #include <util/sock.h>
diff --git a/src/netbase.h b/src/netbase.h
index 9478555d59..51233967b3 100644
--- a/src/netbase.h
+++ b/src/netbase.h
@@ -9,7 +9,7 @@
 #include <config/bitcoin-config.h>
 #endif
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <netaddress.h>
 #include <serialize.h>
 #include <util/sock.h>
diff --git a/src/qt/main.cpp b/src/qt/main.cpp
index a1220b9a59..eca9e9d88f 100644
--- a/src/qt/main.cpp
+++ b/src/qt/main.cpp
@@ -4,7 +4,7 @@
 
 #include <qt/bitcoin.h>
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <util/translation.h>
 #include <util/url.h>
 
diff --git a/src/random.cpp b/src/random.cpp
index 7d3b20bd65..ec8a46b328 100644
--- a/src/random.cpp
+++ b/src/random.cpp
@@ -11,7 +11,7 @@
 #include <crypto/sha512.h>
 #include <support/cleanse.h>
 #ifdef WIN32
-#include <compat.h> // for Windows API
+#include <compat/compat.h>
 #include <wincrypt.h>
 #endif
 #include <logging.h>
diff --git a/src/randomenv.cpp b/src/randomenv.cpp
index 06ac6d8f93..d722256544 100644
--- a/src/randomenv.cpp
+++ b/src/randomenv.cpp
@@ -16,7 +16,7 @@
 #include <support/cleanse.h>
 #include <util/time.h> // for GetTime()
 #ifdef WIN32
-#include <compat.h> // for Windows API
+#include <compat/compat.h>
 #endif
 
 #include <algorithm>
diff --git a/src/stats/rawsender.h b/src/stats/rawsender.h
index d91f6c0def..fc0b0d6795 100644
--- a/src/stats/rawsender.h
+++ b/src/stats/rawsender.h
@@ -6,7 +6,7 @@
 #ifndef BITCOIN_STATS_RAWSENDER_H
 #define BITCOIN_STATS_RAWSENDER_H
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <sync.h>
 #include <threadinterrupt.h>
 
diff --git a/src/test/fuzz/util.h b/src/test/fuzz/util.h
index 43864a5453..ebf741651b 100644
--- a/src/test/fuzz/util.h
+++ b/src/test/fuzz/util.h
@@ -9,7 +9,7 @@
 #include <attributes.h>
 #include <chainparamsbase.h>
 #include <coins.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/amount.h>
 #include <consensus/consensus.h>
 #include <key.h>
diff --git a/src/test/fuzz/util/net.cpp b/src/test/fuzz/util/net.cpp
index a1494f8d3b..f8e996cfa5 100644
--- a/src/test/fuzz/util/net.cpp
+++ b/src/test/fuzz/util/net.cpp
@@ -2,7 +2,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <netaddress.h>
 #include <test/fuzz/FuzzedDataProvider.h>
 #include <util/strencodings.h>
diff --git a/src/test/net_peer_connection_tests.cpp b/src/test/net_peer_connection_tests.cpp
index 2a09791daf..c232baa93d 100644
--- a/src/test/net_peer_connection_tests.cpp
+++ b/src/test/net_peer_connection_tests.cpp
@@ -3,7 +3,7 @@
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
 #include <chainparams.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <net.h>
 #include <net_processing.h>
 #include <netaddress.h>
diff --git a/src/test/net_tests.cpp b/src/test/net_tests.cpp
index 02a958185f..1ff098cd1f 100644
--- a/src/test/net_tests.cpp
+++ b/src/test/net_tests.cpp
@@ -6,7 +6,7 @@
 
 #include <chainparams.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <net.h>
 #include <net_processing.h>
 #include <netaddress.h>
diff --git a/src/test/sock_tests.cpp b/src/test/sock_tests.cpp
index 9e98f4f0b1..fa95fc0ba5 100644
--- a/src/test/sock_tests.cpp
+++ b/src/test/sock_tests.cpp
@@ -2,7 +2,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <test/util/setup_common.h>
 #include <threadinterrupt.h>
 #include <util/sock.h>
diff --git a/src/test/util/net.h b/src/test/util/net.h
index 4c2be00e49..7ca37616e5 100644
--- a/src/test/util/net.h
+++ b/src/test/util/net.h
@@ -5,7 +5,7 @@
 #ifndef BITCOIN_TEST_UTIL_NET_H
 #define BITCOIN_TEST_UTIL_NET_H
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <net.h>
 #include <net_permissions.h>
 #include <net_processing.h>
diff --git a/src/torcontrol.cpp b/src/torcontrol.cpp
index 26154a9939..a89099ecfd 100644
--- a/src/torcontrol.cpp
+++ b/src/torcontrol.cpp
@@ -7,7 +7,7 @@
 
 #include <chainparams.h>
 #include <chainparamsbase.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <crypto/hmac_sha256.h>
 #include <net.h>
 #include <netaddress.h>
diff --git a/src/util/edge.h b/src/util/edge.h
index 8e3ec357a1..7ac354c8bf 100644
--- a/src/util/edge.h
+++ b/src/util/edge.h
@@ -5,7 +5,7 @@
 #ifndef BITCOIN_UTIL_EDGE_H
 #define BITCOIN_UTIL_EDGE_H
 
-#include <compat.h>
+#include <compat/compat.h>
 
 #include <assert.h>
 #include <cstdint>
diff --git a/src/util/sock.cpp b/src/util/sock.cpp
index 1d12669652..87e63b70c3 100644
--- a/src/util/sock.cpp
+++ b/src/util/sock.cpp
@@ -2,7 +2,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <logging.h>
 #include <threadinterrupt.h>
 #include <tinyformat.h>
diff --git a/src/util/sock.h b/src/util/sock.h
index 4c18e71e0c..4d32d50e5e 100644
--- a/src/util/sock.h
+++ b/src/util/sock.h
@@ -5,7 +5,7 @@
 #ifndef BITCOIN_UTIL_SOCK_H
 #define BITCOIN_UTIL_SOCK_H
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <threadinterrupt.h>
 #include <util/time.h>
 
diff --git a/src/util/system.h b/src/util/system.h
index 5779beb065..2983107c22 100644
--- a/src/util/system.h
+++ b/src/util/system.h
@@ -16,8 +16,8 @@
 #endif
 
 #include <attributes.h>
-#include <compat.h>
 #include <compat/assumptions.h>
+#include <compat/compat.h>
 #include <consensus/amount.h>
 #include <fs.h>
 #include <logging.h>
diff --git a/src/util/time.cpp b/src/util/time.cpp
index 2b9a469d9a..80f6891328 100644
--- a/src/util/time.cpp
+++ b/src/util/time.cpp
@@ -7,7 +7,7 @@
 #include <config/bitcoin-config.h>
 #endif
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <util/time.h>
 
 #include <util/check.h>
diff --git a/src/util/time.h b/src/util/time.h
index 306a1ae3f2..32bdebb205 100644
--- a/src/util/time.h
+++ b/src/util/time.h
@@ -6,7 +6,7 @@
 #ifndef BITCOIN_UTIL_TIME_H
 #define BITCOIN_UTIL_TIME_H
 
-#include <compat.h>
+#include <compat/compat.h>
 
 #include <chrono>
 #include <stdint.h>
diff --git a/src/wallet/bdb.cpp b/src/wallet/bdb.cpp
index 1509f9c177..4d642192ce 100644
--- a/src/wallet/bdb.cpp
+++ b/src/wallet/bdb.cpp
@@ -3,6 +3,7 @@
 // Distributed under the MIT software license, see the accompanying
 // file COPYING or http://www.opensource.org/licenses/mit-license.php.
 
+#include <compat/compat.h>
 #include <fs.h>
 #include <wallet/bdb.h>
 #include <wallet/db.h>