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

f7dc992 compat: document redefining ssize_t when using MSVC (fanquake)
3be7ee7 compat: document error-code mapping (fanquake)
3f1d2fb compat: document sockopt_arg_type definition (fanquake)
fb6db6f compat: document S_I* defines when building for Windows (fanquake)
203e682 compat: extract and document MAX_PATH (fanquake)
b63ddb7 compat: remove unused WSA* definitions (fanquake)
7c3df5e compat: document FD_SETSIZE redefinition for WIN32 (fanquake)
cc7b2fd 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 f7dc992
  hebasto:
    re-ACK f7dc992

Tree-SHA512: 9e7e90261a97eae7998ef8d140d8ffab504cccf19abb44ca253d8919a067bb01e3fa9876a44194a1a9fb08a4b0489376844f827d8a27aa66c0f99c60ad5d7041

Author: MacroFake

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 \

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>

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>

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>

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>

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>

src/compat.h renamed to 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

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

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>

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>