Merge bitcoin/bitcoin#25493: compat: document code in compat.h

f7dc99244c8e78dbd0196f612690efcc449c37dc compat: document redefining ssize_t when using MSVC (fanquake)
3be7ee750fd0d31d6e995140025e0d18e6aa788e compat: document error-code mapping (fanquake)
3f1d2fb035bf6413c33847326ac5938802cd5860 compat: document sockopt_arg_type definition (fanquake)
fb6db6fb0eb96f96dc331f565acaa8193f285ab2 compat: document S_I* defines when building for Windows (fanquake)
203e682d22a89af23dab21418e841e3b54b136d4 compat: extract and document MAX_PATH (fanquake)
b63ddb7e6d5c0463b4b8888ae015df87a381c0f6 compat: remove unused WSA* definitions (fanquake)
7c3df5e548ee3404d1ad5b47410dd7b6f77258d3 compat: document FD_SETSIZE redefinition for WIN32 (fanquake)
cc7b2fdd70da439c3cf8daef3bb79cf593f1cef3 refactor: move compat.h into compat/ (fanquake)

Pull request description:

  Move `compat.h` into `compat/`, and document what is in there.

ACKs for top commit:
  vasild:
    ACK f7dc99244c8e78dbd0196f612690efcc449c37dc
  hebasto:
    re-ACK f7dc99244c8e78dbd0196f612690efcc449c37dc

Tree-SHA512: 9e7e90261a97eae7998ef8d140d8ffab504cccf19abb44ca253d8919a067bb01e3fa9876a44194a1a9fb08a4b0489376844f827d8a27aa66c0f99c60ad5d7041

30 files changed, 56 insertions, 47 deletions

diff --git a/src/Makefile.am b/src/Makefile.am
index 7745f4d7c8..23bc180095 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -133,9 +133,9 @@ BITCOIN_CORE_H = \
   clientversion.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 0db2b75384..7cc956ebda 100644
--- a/src/bitcoin-cli.cpp
+++ b/src/bitcoin-cli.cpp
@@ -9,7 +9,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 e0d5c6e5dc..b006353cb0 100644
--- a/src/bitcoin-tx.cpp
+++ b/src/bitcoin-tx.cpp
@@ -8,7 +8,7 @@
 
 #include <clientversion.h>
 #include <coins.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/amount.h>
 #include <consensus/consensus.h>
 #include <core_io.h>
diff --git a/src/bitcoin-util.cpp b/src/bitcoin-util.cpp
index 1739804edb..fb184c0486 100644
--- a/src/bitcoin-util.cpp
+++ b/src/bitcoin-util.cpp
@@ -11,7 +11,7 @@
 #include <chainparams.h>
 #include <chainparamsbase.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <core_io.h>
 #include <streams.h>
 #include <util/system.h>
diff --git a/src/bitcoin-wallet.cpp b/src/bitcoin-wallet.cpp
index 7bec3292a1..a7d49452b0 100644
--- a/src/bitcoin-wallet.cpp
+++ b/src/bitcoin-wallet.cpp
@@ -9,7 +9,7 @@
 #include <chainparams.h>
 #include <chainparamsbase.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <interfaces/init.h>
 #include <key.h>
 #include <logging.h>
diff --git a/src/bitcoind.cpp b/src/bitcoind.cpp
index be894e192e..85ba88f6ab 100644
--- a/src/bitcoind.cpp
+++ b/src/bitcoind.cpp
@@ -9,7 +9,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
index 0a44b98b4e..a8e5552c0a 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,49 +37,54 @@
 #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
 #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
+#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
-#if !defined(ssize_t)
-#ifdef _WIN64
-typedef int64_t ssize_t;
-#else
-typedef int32_t ssize_t;
-#endif
-#endif
+#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
@@ -119,4 +127,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/httpserver.cpp b/src/httpserver.cpp
index b8f69b038c..8e00a6278f 100644
--- a/src/httpserver.cpp
+++ b/src/httpserver.cpp
@@ -9,7 +9,7 @@
 #include <httpserver.h>
 
 #include <chainparamsbase.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <netbase.h>
 #include <node/interface_ui.h>
 #include <rpc/protocol.h> // For HTTP status codes
diff --git a/src/i2p.cpp b/src/i2p.cpp
index 8611984555..c45bcc15d2 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 433fcc3a08..eb0a10103d 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 235e6f904c..6262e51879 100644
--- a/src/mapport.cpp
+++ b/src/mapport.cpp
@@ -19,7 +19,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 6151ab9e08..e9aa7ee43b 100644
--- a/src/net.cpp
+++ b/src/net.cpp
@@ -13,7 +13,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 f3be7e8dff..2036e9078c 100644
--- a/src/net.h
+++ b/src/net.h
@@ -8,7 +8,7 @@
 
 #include <chainparams.h>
 #include <common/bloom.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <node/connection_types.h>
 #include <consensus/amount.h>
 #include <crypto/siphash.h>
diff --git a/src/netaddress.h b/src/netaddress.h
index 47ba045334..e52beb783d 100644
--- a/src/netaddress.h
+++ b/src/netaddress.h
@@ -9,7 +9,7 @@
 #include <config/bitcoin-config.h>
 #endif
 
-#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 030f462ed9..4b8d2f8d0c 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 bf7522210d..fadc8b418e 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 38b0ac71a3..e8f39584ad 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 fca4b5041a..f92e679a00 100644
--- a/src/random.cpp
+++ b/src/random.cpp
@@ -10,7 +10,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 c5dca346d6..9e58180b7a 100644
--- a/src/randomenv.cpp
+++ b/src/randomenv.cpp
@@ -15,7 +15,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/test/fuzz/util.h b/src/test/fuzz/util.h
index b0893e7926..60e2875953 100644
--- a/src/test/fuzz/util.h
+++ b/src/test/fuzz/util.h
@@ -8,7 +8,7 @@
 #include <arith_uint256.h>
 #include <chainparamsbase.h>
 #include <coins.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <consensus/amount.h>
 #include <consensus/consensus.h>
 #include <merkleblock.h>
diff --git a/src/test/net_tests.cpp b/src/test/net_tests.cpp
index f2eaa0179f..f6642d3218 100644
--- a/src/test/net_tests.cpp
+++ b/src/test/net_tests.cpp
@@ -4,7 +4,7 @@
 
 #include <chainparams.h>
 #include <clientversion.h>
-#include <compat.h>
+#include <compat/compat.h>
 #include <cstdint>
 #include <net.h>
 #include <net_processing.h>
diff --git a/src/test/sock_tests.cpp b/src/test/sock_tests.cpp
index 01a402833d..8376ec1a68 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 7f61a03d27..ec6b4e6e88 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 <node/eviction.h>
 #include <netaddress.h>
 #include <net.h>
diff --git a/src/torcontrol.cpp b/src/torcontrol.cpp
index d6e792a55f..3a21a79a34 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/sock.cpp b/src/util/sock.cpp
index 2588575d81..125dbc7f18 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 b854609c22..38a7dc80d6 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 04c66341d3..fa03e88920 100644
--- a/src/util/system.h
+++ b/src/util/system.h
@@ -14,7 +14,7 @@
 #include <config/bitcoin-config.h>
 #endif
 
-#include <compat.h>
+#include <compat/compat.h>
 #include <compat/assumptions.h>
 #include <fs.h>
 #include <logging.h>
diff --git a/src/util/time.cpp b/src/util/time.cpp
index 2cafc55c69..f6d37347f8 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 <tinyformat.h>
 #include <util/time.h>
 #include <util/check.h>
diff --git a/src/util/time.h b/src/util/time.h
index fc49f23ce3..c75b1e94ed 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 <cstdint>
diff --git a/src/wallet/bdb.cpp b/src/wallet/bdb.cpp
index dbd768a758..60715ff3c8 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>