Transparently add the \\?\ prefix to Win32 calls for extended length path handling

On Windows, there is a built-in maximum path limitation of 260 characters under most conditions. This can be extended to 32767 characters under either of the following two conditions:

- Adding the longPathAware attribute to the executable's manifest AND enabling the LongPathsEnabled system-wide registry key or group policy.
- Ensuring fully qualified paths passed to Win32 APIs are prefixed with \\?\

Unfortunately, the former is not realistic for the Swift ecosystem, since it requires developers to have awareness of this specific Windows limitation, AND set longPathAware in their apps' manifest AND expect end users of those apps to change their system configuration.

Instead, this patch transparently prefixes all eligible paths in calls to Win32 APIs with the \\?\ prefix to allow them to work with paths longer than 260 characters without requiring the caller of System to manually prefix the paths.

See https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation for more info.

Author: jakepetroules

Sources/System/FilePath/FilePathTempWindows.swift

@@ -40,7 +40,7 @@ fileprivate func forEachFile(
 
   try searchPath.withPlatformString { szPath in
     var findData = WIN32_FIND_DATAW()
-    let hFind = FindFirstFileW(szPath, &findData)
+    let hFind = try szPath.withCanonicalPathRepresentation({ szPath in FindFirstFileW(szPath, &findData) })
     if hFind == INVALID_HANDLE_VALUE {
       throw Errno(windowsError: GetLastError())
     }
@@ -95,8 +95,8 @@ internal func _recursiveRemove(
     let subpath = path.appending(component)
 
     if (findData.dwFileAttributes & DWORD(FILE_ATTRIBUTE_DIRECTORY)) == 0 {
-      try subpath.withPlatformString {
-        if !DeleteFileW($0) {
+      try subpath.withPlatformString { subpath in
+        if try !subpath.withCanonicalPathRepresentation({ DeleteFileW($0) }) {
           throw Errno(windowsError: GetLastError())
         }
       }
@@ -105,7 +105,7 @@ internal func _recursiveRemove(
 
   // Finally, delete the parent
   try path.withPlatformString {
-    if !RemoveDirectoryW($0) {
+    if try !$0.withCanonicalPathRepresentation({ RemoveDirectoryW($0) }) {
       throw Errno(windowsError: GetLastError())
     }
   }

Sources/System/FilePath/FilePathWindows.swift

@@ -461,3 +461,39 @@ extension SystemString {
     return lexer.current
   }
 }
+
+#if os(Windows)
+extension UnsafePointer where Pointee == CInterop.PlatformChar {
+  /// Invokes `body` with a resolved and potentially `\\?\`-prefixed version of the pointee,
+  /// to ensure long paths greater than 260 characters are handled correctly.
+  ///
+  /// - seealso: https://learn.microsoft.com/en-us/windows/win32/fileio/maximum-file-path-limitation
+  internal func withCanonicalPathRepresentation<Result>(_ body: (Self) throws -> Result) throws -> Result {
+    // 1. Normalize the path first.
+    // Contrary to the documentation, this works on long paths independently
+    // of the registry or process setting to enable long paths (but it will also
+    // not add the \\?\ prefix required by other functions under these conditions).
+    let dwLength: DWORD = GetFullPathNameW(self, 0, nil, nil)
+    return try withUnsafeTemporaryAllocation(of: WCHAR.self, capacity: Int(dwLength)) { fullPath in
+      guard GetFullPathNameW(self, DWORD(fullPath.count), fullPath.baseAddress, nil) > 0 else {
+        throw Errno(rawValue: _mapWindowsErrorToErrno(GetLastError()))
+      }
+
+      // 2. Canonicalize the path.
+      // This will add the \\?\ prefix if needed based on the path's length.
+      let capacity = Int16.max
+      return try withUnsafeTemporaryAllocation(of: WCHAR.self, capacity: numericCast(capacity)) { outBuffer in
+        let flags: ULONG = numericCast(PATHCCH_ALLOW_LONG_PATHS.rawValue)
+        let result = PathCchCanonicalizeEx(outBuffer.baseAddress, numericCast(capacity), fullPath.baseAddress, flags)
+        switch result {
+        case S_OK:
+          // 3. Perform the operation on the normalized path.
+          return try body(outBuffer.baseAddress!)
+        default:
+          throw Errno(rawValue: _mapWindowsErrorToErrno(GetLastError()))
+        }
+      }
+    }
+  }
+}
+#endif

Sources/System/Internals/WindowsSyscallAdapters.swift

@@ -35,15 +35,23 @@ internal func open(
     bInheritHandle: decodedFlags.bInheritHandle
   )
 
-  let hFile = CreateFileW(path,
-                          decodedFlags.dwDesiredAccess,
-                          DWORD(FILE_SHARE_DELETE
-                                  | FILE_SHARE_READ
-                                  | FILE_SHARE_WRITE),
-                          &saAttrs,
-                          decodedFlags.dwCreationDisposition,
-                          decodedFlags.dwFlagsAndAttributes,
-                          nil)
+  let hFile: HANDLE
+  do {
+    hFile = try path.withCanonicalPathRepresentation({ path in
+      CreateFileW(path,
+                  decodedFlags.dwDesiredAccess,
+                  DWORD(FILE_SHARE_DELETE
+                        | FILE_SHARE_READ
+                        | FILE_SHARE_WRITE),
+                  &saAttrs,
+                  decodedFlags.dwCreationDisposition,
+                  decodedFlags.dwFlagsAndAttributes,
+                  nil)
+    })
+  } catch {
+    ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
+    return -1
+  }
 
   if hFile == INVALID_HANDLE_VALUE {
     ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
@@ -77,15 +85,23 @@ internal func open(
     bInheritHandle: decodedFlags.bInheritHandle
   )
 
-  let hFile = CreateFileW(path,
-                          decodedFlags.dwDesiredAccess,
-                          DWORD(FILE_SHARE_DELETE
-                                  | FILE_SHARE_READ
-                                  | FILE_SHARE_WRITE),
-                          &saAttrs,
-                          decodedFlags.dwCreationDisposition,
-                          decodedFlags.dwFlagsAndAttributes,
-                          nil)
+  let hFile: HANDLE
+  do {
+    hFile = try path.withCanonicalPathRepresentation({ path in
+      CreateFileW(path,
+                  decodedFlags.dwDesiredAccess,
+                  DWORD(FILE_SHARE_DELETE
+                        | FILE_SHARE_READ
+                        | FILE_SHARE_WRITE),
+                  &saAttrs,
+                  decodedFlags.dwCreationDisposition,
+                  decodedFlags.dwFlagsAndAttributes,
+                  nil)
+    })
+  } catch {
+    ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
+    return -1
+  }
 
   if hFile == INVALID_HANDLE_VALUE {
     ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
@@ -242,7 +258,12 @@ internal func mkdir(
     bInheritHandle: false
   )
 
-  if !CreateDirectoryW(path, &saAttrs) {
+  do {
+    if try !path.withCanonicalPathRepresentation({ path in CreateDirectoryW(path, &saAttrs) }) {
+      ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
+      return -1
+    }
+  } catch {
     ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
     return -1
   }
@@ -254,7 +275,12 @@ internal func mkdir(
 internal func rmdir(
   _ path: UnsafePointer<CInterop.PlatformChar>
 ) -> CInt {
-  if !RemoveDirectoryW(path) {
+  do {
+    if !path.withCanonicalPathRepresentation({ path in RemoveDirectoryW(path) }) {
+      ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
+      return -1
+    }
+  } catch {
     ucrt._set_errno(_mapWindowsErrorToErrno(GetLastError()))
     return -1
   }