Update ns-winsock2-wsaoverlapped.md

[denkisikinoneko]

Uses the correct datatypes as shown by the struct on the page, however:

The presented syntax on the site is incorrect, for modern Windows! It is using the Win16 format of the structure, while in Win32 the structure is typedef'd to OVERLAPPED, along with LPWSAOVERLAPPED to _OVERLAPPED*. Interpreting the structure as-is and passing it to functions in Win32 will cause them to error with WSA_INVALID_HANDLE. I do not know how to modify the displayed struct, any help there would be useful.

Additionally, hEvent is a little unclear when it comes to using it with I/O completion ports, but I'm unsure how to transform the current description.

Relevant excerpt from um/WinSock2.h, SDK version 10.0.26100.0:

#ifdef WIN32

#define WSAAPI                  FAR PASCAL
#define WSAEVENT                HANDLE
#define LPWSAEVENT              LPHANDLE
#define WSAOVERLAPPED           OVERLAPPED
typedef struct _OVERLAPPED *    LPWSAOVERLAPPED;

#define WSA_IO_PENDING          (ERROR_IO_PENDING)
#define WSA_IO_INCOMPLETE       (ERROR_IO_INCOMPLETE)
#define WSA_INVALID_HANDLE      (ERROR_INVALID_HANDLE)
#define WSA_INVALID_PARAMETER   (ERROR_INVALID_PARAMETER)
#define WSA_NOT_ENOUGH_MEMORY   (ERROR_NOT_ENOUGH_MEMORY)
#define WSA_OPERATION_ABORTED   (ERROR_OPERATION_ABORTED)

#define WSA_INVALID_EVENT       ((WSAEVENT)NULL)
#define WSA_MAXIMUM_WAIT_EVENTS (MAXIMUM_WAIT_OBJECTS)
#define WSA_WAIT_FAILED         (WAIT_FAILED)
#define WSA_WAIT_EVENT_0        (WAIT_OBJECT_0)
#define WSA_WAIT_IO_COMPLETION  (WAIT_IO_COMPLETION)
#define WSA_WAIT_TIMEOUT        (WAIT_TIMEOUT)
#define WSA_INFINITE            (INFINITE)

#else /* WIN16 */

#define WSAAPI                  FAR PASCAL
typedef DWORD                   WSAEVENT, FAR * LPWSAEVENT;

typedef struct _WSAOVERLAPPED {
    DWORD    Internal;
    DWORD    InternalHigh;
    DWORD    Offset;
    DWORD    OffsetHigh;
    WSAEVENT hEvent;
} WSAOVERLAPPED, FAR * LPWSAOVERLAPPED;

#define WSA_IO_PENDING          (WSAEWOULDBLOCK)
#define WSA_IO_INCOMPLETE       (WSAEWOULDBLOCK)
#define WSA_INVALID_HANDLE      (WSAENOTSOCK)
#define WSA_INVALID_PARAMETER   (WSAEINVAL)
#define WSA_NOT_ENOUGH_MEMORY   (WSAENOBUFS)
#define WSA_OPERATION_ABORTED   (WSAEINTR)

#define WSA_INVALID_EVENT       ((WSAEVENT)NULL)
#define WSA_MAXIMUM_WAIT_EVENTS (MAXIMUM_WAIT_OBJECTS)
#define WSA_WAIT_FAILED         ((DWORD)-1L)
#define WSA_WAIT_EVENT_0        ((DWORD)0)
#define WSA_WAIT_TIMEOUT        ((DWORD)0x102L)
#define WSA_INFINITE            ((DWORD)-1L)

#endif  /* WIN32 */

[prmerger-automator]

@denkisikinoneko : Thanks for your contribution! The author(s) and reviewer(s) have been notified to review your proposed change.

[GrantMeStrength]

Thanks for raising this — the underlying issue is valid and worth fixing. However, there may be a concern with the proposed change:

In Win32, WSAOVERLAPPED is #define'd directly to OVERLAPPED (as your header excerpt shows), and in the OVERLAPPED struct Internal and InternalHigh are typed as ULONG_PTR — not DWORD. So the current docs (ULONG_PTR) may actually be correct for Win32, even though it looks wrong when compared to the Win16 struct definition.

Could you confirm whether the DWORD change is intentional given that WSAOVERLAPPED aliases to OVERLAPPED? We'd like to route this to the WinSock SDK docs owner for a final call before merging. Keeping this open in the meantime.

[Copilot]

Pull request overview

Note

Copilot was unable to run its full agentic suite in this review.

Updates the WSAOVERLAPPED documentation to better match the structure’s datatype expectations and clarify field typings for modern Windows SDK usage.

Changes:

• Updated WSAOVERLAPPED field types for Internal, InternalHigh, and hEvent
• Removed the Pointer sub-section under the struct fields
• Adjusted formatting/indentation for some field type lines and a “see also” link

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[GrantMeStrength]

Thank you for looking at this — the observation about WSAOVERLAPPED being typedef'd to OVERLAPPED in Win32 is correct and worth documenting. However, the changes have the Win16/Win32 distinction backwards:

Internal and InternalHigh (revert to ULONG_PTR): In Win32, WSAOVERLAPPED is #define'd to OVERLAPPED, where these fields are ULONG_PTR (pointer-sized). Changing them to DWORD introduces the Win16 layout, not the Win32 one. The original ULONG_PTR was correct.

Pointer field (restore): The OVERLAPPED struct (which WSAOVERLAPPED maps to in Win32) contains a union with Offset/OffsetHigh and Pointer as alternatives. Removing the Pointer field documentation makes the page incomplete for Win32.

hEvent (WSAEVENT is fine): Changing HANDLE to WSAEVENT is acceptable since WSAEVENT is #define'd to HANDLE in Win32 and is semantically clearer in the WSA context. You can keep this change.

Suggested fix: Revert Internal and InternalHigh back to ULONG_PTR, restore the Pointer field documentation, and keep the hEvent type change.

[GrantMeStrength]

@copilot apply changes based on the comments in this thread

[GrantMeStrength]

Thank you for raising this — you've correctly identified a genuine documentation gap. The observation that WSAOVERLAPPED is typedef'd to OVERLAPPED in Win32 (and LPWSAOVERLAPPED to _OVERLAPPED*) is accurate and worth documenting properly.

However, the changes in this PR unfortunately go in the wrong direction:

• Internal and InternalHigh: These are correctly documented as ULONG_PTR. Changing them to DWORD actually introduces the Win16 layout, not Win32. In the Win32 OVERLAPPED struct, these are pointer-sized (ULONG_PTR) — specifically so they work correctly on 64-bit Windows.
• Pointer field: This should stay — it's part of the Offset/OffsetHigh/Pointer union in OVERLAPPED and removing it makes the page incomplete.
• hEvent: WSAEVENT is itself typedef'd to HANDLE, so this change is neutral but doesn't add clarity.

We're closing this PR, but we'll take your feedback on board and look at doing a proper rewrite of this page to clearly document the Win32 typedef relationship and correct field semantics. We appreciate you digging into this!