Startup and cleanup

• WSAStartup initializes Winsock use and fills one WSADATA result object.
• WSACleanup balances prior successful WSAStartup use.
• WSAGetLastError and WSASetLastError access Winsock-specific error state.

Constants

• AF_INET, SOCK_STREAM, IPPROTO_TCP, INADDR_ANY, and INVALID_SOCKET: base IPv4 and socket constants.
• SOL_SOCKET, SOMAXCONN, TCP_NODELAY, SO_UPDATE_ACCEPT_CONTEXT, and SO_UPDATE_CONNECT_CONTEXT: option and backlog constants.
• SD_RECEIVE, SD_SEND, and SD_BOTH: shutdown selectors.
• FIONBIO and SIO_GET_EXTENSION_FUNCTION_POINTER: I/O-control constants.
• WSAEWOULDBLOCK and WSA_IO_PENDING: common Winsock status codes.
• WSAID_ACCEPTEX, WSAID_CONNECTEX, and WSAID_GETACCEPTEXSOCKADDRS: extension-function identifiers.

Constant example

"windows/ws2_32" use
"control" use

{} () {} [
  AF_INET printStack _:;
  SOCK_STREAM printStack _:;
  INVALID_SOCKET printStack _:;
  WSAEWOULDBLOCK printStack _:;
  SD_BOTH printStack _:;
] "main" exportFunction

Expected Output During Compilation

2
1
18446744073709551615nx
10035
2

Declared schemas

• FN_ACCEPTEXRef, FN_CONNECTEXRef, and FN_GETACCEPTEXSOCKADDRSRef: extension-function callback schemas used after lookup through WSAIoctl.
• WSAOVERLAPPED_COMPLETION_ROUTINERef: overlapped completion callback schema.
• WSABUF: byte-count and buffer-address pair used by overlapped send and receive functions.
• WSADATA: startup-data schema containing version fields, descriptive text fields, maximum counts, and vendor pointer.
• addrinfo: address-resolution result schema with family, type, protocol, canon name, address pointer, and next pointer.
• fd_set: descriptor-count field and fixed descriptor array for select.
• sockaddr: generic address family and raw address bytes.
• sockaddr_in: IPv4 address schema with family, port, address, and zero padding.
• timeval: second and microsecond timeout schema for select.

Schema example

"windows/ws2_32" use
"control" use

{} () {} [
  WSABUF fieldCount printStack _:;
  sockaddr_in fieldCount printStack _:;
  sockaddr_in 2 fieldName printStack _:;
] "main" exportFunction

Expected Output During Compilation

2
4
"sin_addr"

Socket and address model

• This module exposes socket values directly as Natx.
• socket produces one raw socket value, and functions such as bind, connect, listen, recv, send, shutdown, ioctlsocket, closesocket, WSARecv, WSASend, WSAIoctl, and WSAGetOverlappedResult consume that same raw value directly.
• sockaddr_in.sin_port and sockaddr_in.sin_addr are passed in network byte order.
• htonl and htons convert host-order IPv4 addresses and ports before those fields are assigned, and ntohl and ntohs convert them back.

Arguments and results

• getaddrinfo.pNodeName and pServiceName take raw zero-terminated byte strings or 0nx.
• bind.name and connect.name are borrowed read-only pointers to one sockaddr-compatible address block, and namelen is the corresponding byte size.
• WSAIoctl.lpvInBuffer and lpvOutBuffer are raw caller-owned buffer addresses. Extension-function lookup passes one WSAID_* value through the input buffer and writes one function-pointer result into caller-owned output storage.
• fd_set.fd_array is a fixed Natx 64 array, so fd_count must remain within that declared capacity.
• sockaddr, sockaddr_in, and the ai_addr field of addrinfo are exposed through raw address storage or raw pointer-shaped values and are interpreted by caller-side code according to the selected family.
• lpdwBytesReceived, lpdwBytesSent, lpNumberOfBytesRecvd, lpNumberOfBytesSent, lpcbBytesReturned, lpFlags, and similar pointers are caller-owned writable storage.
• When an overlapped operation completes immediately, those pointers may receive the immediate result directly. When the operation reports WSA_IO_PENDING, final completion is obtained later through the queued completion path or through WSAGetOverlappedResult.
• socket reports failure through INVALID_SOCKET.
• Many Winsock calls report failure through one negative Int32 result and leave details in WSAGetLastError.
• recv and send report failure through -1, and stream recv returning 0 reports peer closure.
• WSAEWOULDBLOCK reports that one nonblocking operation would block, and WSA_IO_PENDING reports one pending overlapped operation.
• getaddrinfo returns one result code directly.
• Each successful socket result is released with closesocket.
• getaddrinfo returns one linked result list through ppResult, and freeaddrinfo releases that list.
• WSAIoctl borrows caller-owned input and output buffers and does not retain them after the call returns.
• OVERLAPPED storage remains caller-owned until completion is observed or the operation is canceled.

Readiness, nonblocking, and AcceptEx

• ioctlsocket takes one raw writable argument pointer, and FIONBIO is the declared control code commonly used to change nonblocking state.
• select takes caller-owned mutable fd_set records for read, write, and exception interest together with one caller-owned timeval pointer.
• fd_set.fd_array has fixed declared capacity 64, so caller-side descriptor sets remain bounded by that storage.
• WSAEWOULDBLOCK is the declared status code for the nonblocking would-block condition.
• AcceptEx writes accepted-address data into one caller-owned output buffer.
• When dwReceiveDataLength is nonzero, the same buffer also begins with the first received data bytes.
• dwLocalAddressLength and dwRemoteAddressLength describe the buffer portions reserved for the local and remote address records.
• GetAcceptExSockaddrs interprets that same buffer and returns raw address pointers and byte lengths into it.

Overlapped I/O

• WSARecv and WSASend use one or more WSABUF descriptors to describe transferred buffers.
• When an overlapped operation is pending, the call reports that state through WSA_IO_PENDING and completion is observed through the supplied OVERLAPPED object.
• WSAGetOverlappedResult retrieves completion state, transferred-byte count, and final flags for one overlapped operation.
• The completion-routine argument may be NIL when completion is observed through one completion-port queue.
• The supplied OVERLAPPED object is caller-owned and may be embedded as the first field of one larger caller-owned context object that also stores callback or user-state data.

Extension-function lookup

AcceptEx, ConnectEx, and GetAcceptExSockaddrs are not imported directly. Their identifiers and callback schemas are provided for lookup through WSAIoctl with SIO_GET_EXTENSION_FUNCTION_POINTER.

• WSAID_ACCEPTEX pairs with FN_ACCEPTEXRef.
• WSAID_CONNECTEX pairs with FN_CONNECTEXRef.
• WSAID_GETACCEPTEXSOCKADDRS pairs with FN_GETACCEPTEXSOCKADDRSRef.
• The lookup writes one raw function pointer into caller-owned output storage. Caller code then casts that pointer to the corresponding callback schema.

Imported functions

• WSAStartup, WSACleanup, WSAGetLastError, and WSASetLastError: startup and error operations.
• WSAIoctl, WSAGetOverlappedResult, WSARecv, and WSASend: overlapped I/O operations.
• socket, closesocket, bind, connect, listen, shutdown, setsockopt, ioctlsocket, and select: socket lifecycle and configuration operations.
• recv and send: stream receive and send operations.
• getaddrinfo, freeaddrinfo, htonl, htons, ntohl, and ntohs: address-resolution and byte-order helpers.

Signature examples

Printing imported names during compilation shows the exact imported signatures.

"windows/ws2_32" use
"control" use

{} Int32 {} [
  @WSAStartup printStack _:;
  @WSARecv printStack _:;
  @socket printStack _:;
  0
] "main" exportFunction

Expected Output During Compilation

{wVersionRequested: Nat16; lpWSAData: {wVersion: Nat16; wHighVersion: Nat16; iMaxSockets: Nat16; iMaxUdpDg: Nat16; lpVendorInfo: Nat8 Ref; szDescription: Nat8 257 array; szSystemStatus: Nat8 129 array;} Ref;} Int32 {convention: "";} codeRef
{s: Natx; lpBuffers: {len: Nat32; buf: Natx;} Ref; dwBufferCount: Nat32; lpNumberOfBytesRecvd: Nat32 Ref; lpFlags: Nat32 Ref; lpOverlapped: {Internal: Natx; InternalHigh: Natx; DUMMYUNIONNAME: Nat64; hEvent: Natx;} Ref; lpCompletionRoutine: {dwError: Nat32; cbTransferred: Nat32; lpOverlapped: {Internal: Natx; InternalHigh: Natx; DUMMYUNIONNAME: Nat64; hEvent: Natx;} Ref; dwFlags: Nat32;} () {convention: "";} codeRef;} Int32 {convention: "";} codeRef
{af: Int32; type: Int32; protocol: Int32;} Natx {convention: "";} codeRef

See also

• windows/dispatcher: Windows completion-port dispatcher and callback posting helpers.
• windows/kernel32: Kernel32 declarations for synchronization, process, thread, file, and timing helpers.
• linux/socket: Linux socket declarations, constants, address schemas, and imported functions.
• sync/sync: Cross-platform scheduling, sleep, time, IPv4 formatting, and TCP helpers.
• sync/TcpAcceptor: Listening TCP acceptor with address reporting and accepted connection creation.
• sync/TcpConnection: Connected TCP stream with buffered read, string read, write, and shutdown operations.