From 3c6fbc31841a7126730459b0959415a0a7fbbc13 Mon Sep 17 00:00:00 2001 From: Graeme Geldenhuys Date: Tue, 23 Jun 2026 00:22:33 +0100 Subject: [PATCH] stdlib: flag Linux-specific porting boundaries in Net.Sockets and Security.Guid Document that the socket constants/sockaddr_in layout (Net.Sockets) and the getrandom(2) call (Security.Guid) are Linux x86_64 specifics, with the per-OS differences and the fact that the public helper API is the stable surface a future port keeps. --- stdlib/src/main/pascal/net.sockets.pas | 12 ++++++++++++ stdlib/src/main/pascal/security.guid.pas | 7 +++++++ 2 files changed, 19 insertions(+) diff --git a/stdlib/src/main/pascal/net.sockets.pas b/stdlib/src/main/pascal/net.sockets.pas index 89afeac..64e9cff 100644 --- a/stdlib/src/main/pascal/net.sockets.pas +++ b/stdlib/src/main/pascal/net.sockets.pas @@ -27,6 +27,18 @@ unit Net.Sockets; interface +{ ponytail: PORTING BOUNDARY — the constants and the sockaddr_in layout below + are LINUX x86_64 values. Other targets differ and need a per-platform layer: + * macOS/BSD: SO_REUSEADDR=4, O_NONBLOCK=4 (impl section), and TSockAddrIn + starts with a sin_len:Byte before sin_family; MSG_NOSIGNAL does not exist + (use the SO_NOSIGPIPE socket option, or keep IgnoreSigPipe). + * Windows: a separate Winsock backend (ws2_32, WSAStartup, closesocket, + SOCKET handles, WSAGetLastError). + The helper API (TcpListen*/TcpConnect*/AcceptConn/RecvString/SendAll/Close/ + MakeNonBlocking/IgnoreSigPipe) is the stable surface — callers never touch + these constants — so a future port changes only the implementation, not + consumers. Add the platform split when a second target lands. } + const { address families / socket types } AF_INET = 2; diff --git a/stdlib/src/main/pascal/security.guid.pas b/stdlib/src/main/pascal/security.guid.pas index fe9138b..e3899f9 100644 --- a/stdlib/src/main/pascal/security.guid.pas +++ b/stdlib/src/main/pascal/security.guid.pas @@ -32,6 +32,13 @@ implementation uses StrUtils; { TStringBuilder } +{ ponytail: PORTING BOUNDARY — getrandom(2) is LINUX-specific (3.17+, glibc + 2.25+). FreeBSD has a compatible getrandom; macOS does NOT (use getentropy(3) + or SecRandomCopyBytes); Windows uses BCryptGenRandom. When a second target + lands, dispatch c_getrandom per platform behind NewGuidRaw — the public API + (NewGuid/NewGuidRaw) stays put. (/dev/urandom would cover all the Unixes but + not Windows, hence the syscall.) } + { getrandom(buf, buflen, flags): fill buf with buflen random bytes from the kernel CSPRNG. flags=0 reads from the same pool as /dev/urandom. } function c_getrandom(ABuf: Pointer; ALen: Int64; AFlags: Integer): Int64;