From 5d79870aec85d2a2e15b9cac808cae21b5bcbce9 Mon Sep 17 00:00:00 2001 From: Dan Gohman Date: Tue, 5 Oct 2021 14:24:40 -0700 Subject: [PATCH] Document the valid values for `HandleOrNull` and `HandleOrInvalid`. --- library/std/src/os/windows/io/handle.rs | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/library/std/src/os/windows/io/handle.rs b/library/std/src/os/windows/io/handle.rs index b1edc6c511f0e..1527f5b6b07e0 100644 --- a/library/std/src/os/windows/io/handle.rs +++ b/library/std/src/os/windows/io/handle.rs @@ -68,6 +68,10 @@ pub struct OwnedHandle { /// `NULL`. This ensures that such FFI calls cannot start using the handle without /// checking for `NULL` first. /// +/// This type concerns any value other than `NULL` to be valid, including `INVALID_HANDLE_VALUE`. +/// This is because APIs that use `NULL` as their sentry value don't treat `INVALID_HANDLE_VALUE` +/// as special. +/// /// If this holds a valid handle, it will close the handle on drop. #[repr(transparent)] #[unstable(feature = "io_safety", issue = "87074")] @@ -84,6 +88,10 @@ pub struct HandleOrNull(OwnedHandle); /// `INVALID_HANDLE_VALUE`. This ensures that such FFI calls cannot start using the handle without /// checking for `INVALID_HANDLE_VALUE` first. /// +/// This type concerns any value other than `INVALID_HANDLE_VALUE` to be valid, including `NULL`. +/// This is because APIs that use `INVALID_HANDLE_VALUE` as their sentry value may return `NULL` +/// under `windows_subsystem = "windows"` or other situations where I/O devices are detached. +/// /// If this holds a valid handle, it will close the handle on drop. #[repr(transparent)] #[unstable(feature = "io_safety", issue = "87074")]