Coverage for /pythoncovmergedfiles/medio/medio/usr/local/lib/python3.11/site-packages/filelock/_windows.py: 6%
Shortcuts on this page
r m x toggle line displays
j k next/prev highlighted chunk
0 (zero) top of page
1 (one) first highlighted chunk
1from __future__ import annotations
3__lazy_modules__ = ["filelock._util", "msvcrt", "struct"]
5import os
6import struct
7import sys
8import time
9from contextlib import contextmanager, suppress
10from errno import ENOENT, ENOTDIR, EWOULDBLOCK
11from functools import cache
12from typing import TYPE_CHECKING, Final, cast
14from filelock._api import BaseFileLock
15from filelock._util import raise_on_not_writable_file
17if TYPE_CHECKING:
18 from collections.abc import Generator
20if sys.platform == "win32": # pragma: win32 cover
21 import ctypes
22 import msvcrt
23 from ctypes import wintypes
25 _GENERIC_READ: Final[int] = 0x80000000
26 _GENERIC_WRITE: Final[int] = 0x40000000
27 _SYNCHRONIZE: Final[int] = 0x00100000
28 _DELETE: Final[int] = 0x00010000
29 _DESIRED_ACCESS: Final[int] = _GENERIC_READ | _GENERIC_WRITE | _SYNCHRONIZE
30 _FILE_SHARE_READ_WRITE: Final[int] = (
31 0x00000001 | 0x00000002
32 ) # read | write; matches os.open (_SH_DENYNO), no delete
33 _FILE_OPEN: Final[int] = 1 # open the file only if it exists; the NtCreateFile OPEN_EXISTING
34 _FILE_OPEN_IF: Final[int] = 3 # open the file if it exists, create it otherwise; the NtCreateFile OPEN_ALWAYS
35 # Attribute-only access skips share-mode checks, so the probe sees a name's deletion state rather than a reader.
36 _FILE_READ_ATTRIBUTES: Final[int] = 0x00000080
37 _FILE_SHARE_ALL: Final[int] = 0x00000001 | 0x00000002 | 0x00000004 # read | write | delete
38 _FILE_ATTRIBUTE_READONLY: Final[int] = 0x00000001
39 _FILE_ATTRIBUTE_NORMAL: Final[int] = 0x00000080
40 _FILE_ATTRIBUTE_REPARSE_POINT: Final[int] = 0x00000400
41 # CreateOptions: keep the handle synchronous (the CRT and msvcrt.locking rely on a maintained file position),
42 # refuse a directory, return at once instead of waiting for an oplock holder to answer the break, and open a
43 # reparse point rather than following it so the check below acts on the link itself.
44 _FILE_SYNCHRONOUS_IO_NONALERT: Final[int] = 0x00000020
45 _FILE_NON_DIRECTORY_FILE: Final[int] = 0x00000040
46 _FILE_DELETE_ON_CLOSE: Final[int] = 0x00001000
47 _FILE_COMPLETE_IF_OPLOCKED: Final[int] = 0x00000100
48 _FILE_OPEN_REPARSE_POINT: Final[int] = 0x00200000
49 _CREATE_OPTIONS: Final[int] = (
50 _FILE_SYNCHRONOUS_IO_NONALERT | _FILE_NON_DIRECTORY_FILE | _FILE_COMPLETE_IF_OPLOCKED | _FILE_OPEN_REPARSE_POINT
51 )
52 # Listing access takes part in share-mode checks, unlike attribute-only access, so a handle that holds it without
53 # FILE_SHARE_DELETE blocks renames and removals of the directory until it closes.
54 _FILE_LIST_DIRECTORY: Final[int] = 0x00000001
55 _FILE_DIRECTORY_FILE: Final[int] = 0x00000001
56 _DIRECTORY_OPTIONS: Final[int] = _FILE_SYNCHRONOUS_IO_NONALERT | _FILE_DIRECTORY_FILE | _FILE_OPEN_REPARSE_POINT
57 _OBJ_CASE_INSENSITIVE: Final[int] = 0x00000040 # Win32 name lookups are case-insensitive
58 _OWNER_WRITE: Final[int] = 0o200
59 _GROUP_AND_OTHERS: Final[int] = 0o077
60 # The DACL os.mkdir(mode=0o700) applies, less the inheritance flags a file has no use for: protected, so the
61 # directory's inheritable entries stay out, with full access for SYSTEM, Administrators and the owner.
62 _OWNER_ONLY_SDDL: Final[str] = "D:P(A;;FA;;;SY)(A;;FA;;;BA)(A;;FA;;;OW)"
63 _SDDL_REVISION_1: Final[int] = 1
64 _INVALID_HANDLE_VALUE: Final[int | None] = ctypes.c_void_p(-1).value
66 # LockFileEx locks a byte range at an offset carried in OVERLAPPED, independent of the descriptor's file position.
67 # msvcrt.locking starts at the current position instead, so a metadata write between lock and unlock could shift
68 # the byte a later unlock targets; the explicit offset removes that hazard for both the path lock and #608's
69 # descriptor lock.
70 _LOCKFILE_FAIL_IMMEDIATELY: Final[int] = 0x00000001
71 _LOCKFILE_EXCLUSIVE_LOCK: Final[int] = 0x00000002
72 _ERROR_ACCESS_DENIED: Final[int] = 5
73 _ERROR_LOCK_VIOLATION: Final[int] = 33 # another handle holds the byte range
74 _ERROR_NOT_LOCKED: Final[int] = 158 # the byte range is not locked
76 # NtCreateFile returns the raw NTSTATUS as its value, where CreateFileW collapses several of these into one
77 # ERROR_ACCESS_DENIED. Telling them apart is the point (#604): a name pending deletion or a share conflict is
78 # transient and worth a retry, a real access denial is not.
79 _STATUS_SUCCESS: Final[int] = 0x00000000
80 # A success code that comes with a handle: another handle's oplock is breaking and its holder has not answered yet.
81 _STATUS_OPLOCK_BREAK_IN_PROGRESS: Final[int] = 0x00000108
82 _STATUS_ACCESS_DENIED: Final[int] = 0xC0000022
83 _STATUS_OBJECT_NAME_NOT_FOUND: Final[int] = 0xC0000034
84 _STATUS_OBJECT_PATH_NOT_FOUND: Final[int] = 0xC000003A
85 _STATUS_SHARING_VIOLATION: Final[int] = 0xC0000043
86 _STATUS_DELETE_PENDING: Final[int] = 0xC0000056
87 #: Probes, 2 ms apart, for transient STATUS_ACCESS_DENIED while a peer unlinks the name (#604). A count ensures
88 #: every probe runs even when the process stalls; oplock breaks use the caller's wait instead.
89 _ACCESS_DENIED_PROBES: Final[int] = 250
90 _ACCESS_DENIED_GRACE: Final[float] = 0.5
91 _ACCESS_DENIED_RETRY: Final[float] = 0.002
93 _ntdll: Final[ctypes.WinDLL] = ctypes.WinDLL("ntdll")
94 _kernel32: Final[ctypes.WinDLL] = ctypes.WinDLL("kernel32", use_last_error=True)
95 _advapi32: Final[ctypes.WinDLL] = ctypes.WinDLL("advapi32", use_last_error=True)
97 class _UNICODE_STRING(ctypes.Structure): # ruff:ignore[invalid-class-name] # mirrors the Win32 struct name
98 _fields_ = (
99 ("Length", wintypes.USHORT), # byte length, not character count
100 ("MaximumLength", wintypes.USHORT),
101 ("Buffer", wintypes.LPWSTR),
102 )
104 class _OBJECT_ATTRIBUTES(ctypes.Structure): # ruff:ignore[invalid-class-name] # mirrors the Win32 struct name
105 _fields_ = (
106 ("Length", wintypes.ULONG),
107 ("RootDirectory", wintypes.HANDLE),
108 ("ObjectName", ctypes.POINTER(_UNICODE_STRING)),
109 ("Attributes", wintypes.ULONG),
110 ("SecurityDescriptor", ctypes.c_void_p),
111 ("SecurityQualityOfService", ctypes.c_void_p),
112 )
114 class _IO_STATUS_BLOCK(ctypes.Structure): # ruff:ignore[invalid-class-name] # mirrors the Win32 struct name
115 _fields_ = (
116 ("Status", ctypes.c_void_p), # a union of NTSTATUS and PVOID, so it is pointer-sized
117 ("Information", ctypes.c_void_p),
118 )
120 class _SECURITY_ATTRIBUTES(ctypes.Structure): # ruff:ignore[invalid-class-name] # mirrors the Win32 struct name
121 _fields_ = (
122 ("nLength", wintypes.DWORD),
123 ("lpSecurityDescriptor", ctypes.c_void_p),
124 ("bInheritHandle", wintypes.BOOL),
125 )
127 class _OVERLAPPED(ctypes.Structure): # mirrors the Win32 struct name
128 _fields_ = (
129 ("Internal", ctypes.c_void_p), # ULONG_PTR: pointer-sized, not DWORD, or the x64 layout corrupts Offset
130 ("InternalHigh", ctypes.c_void_p),
131 ("Offset", wintypes.DWORD), # the DUMMYUNIONNAME struct, flattened: low 32 bits of the byte offset
132 ("OffsetHigh", wintypes.DWORD),
133 ("hEvent", wintypes.HANDLE),
134 )
136 class _BY_HANDLE_FILE_INFORMATION(ctypes.Structure): # ruff:ignore[invalid-class-name] # mirrors the Win32 struct name
137 _fields_ = (
138 ("dwFileAttributes", wintypes.DWORD),
139 ("ftCreationTime", wintypes.FILETIME),
140 ("ftLastAccessTime", wintypes.FILETIME),
141 ("ftLastWriteTime", wintypes.FILETIME),
142 ("dwVolumeSerialNumber", wintypes.DWORD),
143 ("nFileSizeHigh", wintypes.DWORD),
144 ("nFileSizeLow", wintypes.DWORD),
145 ("nNumberOfLinks", wintypes.DWORD),
146 ("nFileIndexHigh", wintypes.DWORD),
147 ("nFileIndexLow", wintypes.DWORD),
148 )
150 _ntdll.NtCreateFile.restype = wintypes.LONG # NTSTATUS
151 _ntdll.NtCreateFile.argtypes = [
152 ctypes.POINTER(wintypes.HANDLE),
153 wintypes.DWORD,
154 ctypes.POINTER(_OBJECT_ATTRIBUTES),
155 ctypes.POINTER(_IO_STATUS_BLOCK),
156 ctypes.POINTER(ctypes.c_longlong), # PLARGE_INTEGER AllocationSize
157 wintypes.ULONG,
158 wintypes.ULONG,
159 wintypes.ULONG,
160 wintypes.ULONG,
161 ctypes.c_void_p,
162 wintypes.ULONG,
163 ]
164 _ntdll.RtlDosPathNameToNtPathName_U_WithStatus.restype = wintypes.LONG # NTSTATUS
165 _ntdll.RtlDosPathNameToNtPathName_U_WithStatus.argtypes = [
166 wintypes.LPCWSTR,
167 ctypes.POINTER(_UNICODE_STRING),
168 ctypes.c_void_p,
169 ctypes.c_void_p,
170 ]
171 _ntdll.RtlFreeUnicodeString.restype = None
172 _ntdll.RtlFreeUnicodeString.argtypes = [ctypes.POINTER(_UNICODE_STRING)]
173 _ntdll.RtlNtStatusToDosError.restype = wintypes.ULONG
174 _ntdll.RtlNtStatusToDosError.argtypes = [wintypes.LONG]
176 _kernel32.CloseHandle.argtypes = [wintypes.HANDLE]
177 _kernel32.CloseHandle.restype = wintypes.BOOL
178 _kernel32.GetFileInformationByHandle.argtypes = [wintypes.HANDLE, ctypes.POINTER(_BY_HANDLE_FILE_INFORMATION)]
179 _kernel32.GetFileInformationByHandle.restype = wintypes.BOOL
180 _kernel32.LockFileEx.argtypes = [
181 wintypes.HANDLE,
182 wintypes.DWORD,
183 wintypes.DWORD,
184 wintypes.DWORD,
185 wintypes.DWORD,
186 ctypes.POINTER(_OVERLAPPED),
187 ]
188 _kernel32.LockFileEx.restype = wintypes.BOOL
189 _kernel32.UnlockFileEx.argtypes = [
190 wintypes.HANDLE,
191 wintypes.DWORD,
192 wintypes.DWORD,
193 wintypes.DWORD,
194 ctypes.POINTER(_OVERLAPPED),
195 ]
196 _kernel32.UnlockFileEx.restype = wintypes.BOOL
197 _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW.argtypes = [
198 wintypes.LPCWSTR,
199 wintypes.DWORD,
200 ctypes.POINTER(ctypes.c_void_p),
201 ctypes.POINTER(wintypes.ULONG),
202 ]
203 _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW.restype = wintypes.BOOL
204 _advapi32.GetNamedSecurityInfoW.argtypes = [
205 wintypes.LPCWSTR,
206 ctypes.c_int,
207 wintypes.DWORD,
208 ctypes.POINTER(ctypes.c_void_p),
209 ctypes.POINTER(ctypes.c_void_p),
210 ctypes.POINTER(ctypes.c_void_p),
211 ctypes.POINTER(ctypes.c_void_p),
212 ctypes.POINTER(ctypes.c_void_p),
213 ]
214 _advapi32.GetNamedSecurityInfoW.restype = wintypes.DWORD
215 _advapi32.OpenThreadToken.argtypes = [
216 wintypes.HANDLE,
217 wintypes.DWORD,
218 wintypes.BOOL,
219 ctypes.POINTER(wintypes.HANDLE),
220 ]
221 _advapi32.OpenThreadToken.restype = wintypes.BOOL
222 _advapi32.OpenProcessToken.argtypes = [wintypes.HANDLE, wintypes.DWORD, ctypes.POINTER(wintypes.HANDLE)]
223 _advapi32.OpenProcessToken.restype = wintypes.BOOL
224 _advapi32.GetTokenInformation.argtypes = [
225 wintypes.HANDLE,
226 ctypes.c_int,
227 ctypes.c_void_p,
228 wintypes.DWORD,
229 ctypes.POINTER(wintypes.DWORD),
230 ]
231 _advapi32.GetTokenInformation.restype = wintypes.BOOL
232 _kernel32.GetCurrentProcess.restype = wintypes.HANDLE
233 _kernel32.GetCurrentThread.restype = wintypes.HANDLE
234 _kernel32.LocalFree.argtypes = [ctypes.c_void_p]
235 _kernel32.LocalFree.restype = ctypes.c_void_p
236 _kernel32.CreateDirectoryW.argtypes = [wintypes.LPCWSTR, ctypes.POINTER(_SECURITY_ATTRIBUTES)]
237 _kernel32.CreateDirectoryW.restype = wintypes.BOOL
238 _kernel32.CreateFileW.argtypes = [
239 wintypes.LPCWSTR,
240 wintypes.DWORD,
241 wintypes.DWORD,
242 ctypes.c_void_p,
243 wintypes.DWORD,
244 wintypes.DWORD,
245 wintypes.HANDLE,
246 ]
247 _kernel32.CreateFileW.restype = ctypes.c_void_p
249 def _lock_fd_nonblocking(fd: int) -> bool:
250 # One nonblocking exclusive LockFileEx attempt shared by WindowsFileLock and lock_descriptor, over the one-byte
251 # range at offset 0. True on acquisition, False on contention, raise otherwise. The caller owns fd; the handle
252 # from get_osfhandle belongs to the CRT descriptor and must not be closed here.
253 overlapped = _OVERLAPPED() # zero-initialized, so Offset/OffsetHigh/hEvent are 0
254 flags = _LOCKFILE_EXCLUSIVE_LOCK | _LOCKFILE_FAIL_IMMEDIATELY
255 if _kernel32.LockFileEx(msvcrt.get_osfhandle(fd), flags, 0, 1, 0, ctypes.byref(overlapped)):
256 return True
257 err = ctypes.get_last_error()
258 if err == _ERROR_LOCK_VIOLATION:
259 return False
260 # A non-contention LockFileEx failure is not reproducible in-process.
261 raise ctypes.WinError(err) # pragma: no cover
263 def _unlock_fd(fd: int) -> None:
264 overlapped = _OVERLAPPED() # the same offset 0 and one-byte length the lock used
265 if ( # pragma: no cover # only an interrupted earlier release leaves our own range unlocked
266 not _kernel32.UnlockFileEx(msvcrt.get_osfhandle(fd), 0, 1, 0, ctypes.byref(overlapped))
267 and (err := ctypes.get_last_error()) != _ERROR_NOT_LOCKED
268 ):
269 raise ctypes.WinError(err)
271 class WindowsFileLock(BaseFileLock):
272 """
273 Uses ``LockFileEx`` to hard lock a byte range of the lock file on Windows systems.
275 Lock file cleanup: Windows attempts to delete the lock file after release, but deletion is
276 not guaranteed in multi-threaded scenarios where another thread holds an open handle. The lock
277 file may persist on disk, which does not affect lock correctness.
278 """
280 def _acquire(self) -> None:
281 raise_on_not_writable_file(self._lock_path)
283 # The reparse test is bound to the opened handle, so a symlink or junction swapped in cannot defeat it
284 # through a check-then-open TOCTOU race.
285 try:
286 fd = _open_non_reparse_fd(self._lock_path, self._open_mode())
287 except BlockingIOError:
288 return # an oplock holder has not answered its break; let the retry loop keep its deadline
289 if fd is None:
290 return # open contention (share conflict or a name pending deletion); let the retry loop try again
291 try:
292 locked = _lock_fd_nonblocking(fd)
293 if locked:
294 self._mark_descriptor_owned(fd)
295 except BaseException:
296 # Closing drops the byte-range lock, so a hold already recorded for this descriptor must go with it.
297 self._mark_descriptor_released()
298 os.close(fd)
299 raise
300 if not locked:
301 os.close(fd) # another holder owns the byte-range lock; let the retry loop try again
303 def _release(self) -> None:
304 fd = cast("int", self._context.lock_file_fd)
305 # Retain the descriptor until the OS unlock succeeds: if UnlockFileEx raises, the byte-range lock is still
306 # held, so is_locked must keep reporting held rather than losing the fd. Only after the unlock commits do
307 # close and unlink run as post-unlock cleanup; their failure cannot make the lock held again.
308 _unlock_fd(fd)
309 self._mark_descriptor_released()
310 self._close_released_fd(fd, default_suppresses=False)
311 if not self._preserve_lock_file: # preserve_lock_file keeps a stable file identity for the caller (#605)
312 with suppress(OSError):
313 unlink_without_oplock_wait(self._lock_path)
315 def _open_non_reparse_fd(path: str, mode: int, *, oplock_wait: float = _ACCESS_DENIED_GRACE) -> int | None:
316 """
317 Open *path* for locking while refusing reparse points, bound to the handle actually locked.
319 The file is opened through ``NtCreateFile`` with ``FILE_OPEN_REPARSE_POINT`` so a symlink or junction planted
320 at the path is not followed, and the reparse decision is read from *that* handle via
321 ``GetFileInformationByHandle`` rather than from a prior pathname query. Reading the held handle closes the
322 check-then-open race: an attacker cannot swap the path between validation and use because both act on the same
323 handle. Share mode omits delete so a peer cannot unlink or rename the file out from under a live holder,
324 matching ``os.open``'s ``_SH_DENYNO``.
326 ``NtCreateFile`` is used instead of ``CreateFileW`` because its return value carries the raw ``NTSTATUS``.
327 Windows collapses a transient delete-pending name and a permanent access denial into the same Win32
328 ``ERROR_ACCESS_DENIED``; the status keeps them apart, so a real denial fails fast instead of spinning until the
329 caller's timeout (#604).
331 The reparse option only guards the final path component; Windows still follows reparse points in intermediate
332 directories. This assumes the lock file sits in a lock directory untrusted users cannot modify. A path with
333 attacker-controlled parent directories would need component-by-component handle validation.
335 :param path: the lock file path.
336 :param mode: the permission mode; as ``os.open`` does on Windows, a cleared owner-write bit creates the file
337 read-only. A mode without group and other bits creates it with an owner-only DACL (discretionary access
338 control list, the Windows permission list); any other mode has no Windows counterpart and leaves the file
339 the entries its directory hands down. Both only take effect when the file is created, not when an existing
340 one is opened.
342 :param oplock_wait: seconds to wait for the holder of an oplock on the file to answer its break.
344 :returns: a file descriptor owning the opened handle, or ``None`` on a sharing violation or a delete-pending
345 name, which the caller should treat as contention and retry.
347 :raises BlockingIOError: if an oplock break stays unanswered for *oplock_wait* seconds.
348 :raises OSError: if the path resolves to a reparse point, or the open fails for any other reason, raised with
349 the Win32 error the status maps to. An access denial is raised only once it outlasts a run of probes, since
350 a peer unlinking the file as it releases can make the open answer ``STATUS_ACCESS_DENIED`` for a moment.
352 """
353 # Emit the audit event os.open would, so consumers watching "open" still see the path-level open and can veto.
354 sys.audit("open", path, None, os.O_RDWR | os.O_CREAT)
355 read_only = not mode & _OWNER_WRITE
356 owner_only = not mode & 0o077
357 handle, status = _nt_open(path, read_only=read_only, owner_only=owner_only)
358 denied_probes = 0
359 oplock_deadline = time.monotonic() + oplock_wait
360 while True:
361 if status == _STATUS_ACCESS_DENIED:
362 if denied_probes >= _ACCESS_DENIED_PROBES:
363 break
364 denied_probes += 1
365 elif status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
366 if time.monotonic() >= oplock_deadline:
367 break
368 else:
369 break
370 time.sleep(_ACCESS_DENIED_RETRY)
371 handle, status = _nt_open(path, read_only=read_only, owner_only=owner_only)
372 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
373 msg = "oplock break in progress"
374 raise BlockingIOError(EWOULDBLOCK, msg, path)
375 if status != _STATUS_SUCCESS:
376 if status in {_STATUS_SHARING_VIOLATION, _STATUS_DELETE_PENDING}:
377 return None
378 raise _status_error(status, path)
380 return _descriptor_for_non_reparse(handle, path, os.O_RDWR)
382 def open_read_without_oplock_wait(path: str) -> int:
383 """
384 Open *path* read-only and return a descriptor, without waiting for an oplock holder to answer its break.
386 ``os.open`` waits inside the system call until the holder of an oplock on the file answers or closes its handle,
387 so no timeout or ``blocking=False`` ends the wait. A reparse point at *path* is refused rather than followed.
389 :param path: the file to read.
391 :returns: a read-only file descriptor.
393 :raises BlockingIOError: if an oplock break is in progress, which callers treat as contention.
394 :raises FileNotFoundError: if *path* does not exist.
395 :raises OSError: if the open fails for any other reason, or *path* is a reparse point.
397 """
398 sys.audit("open", path, None, os.O_RDONLY)
399 return _open_existing_without_oplock_wait(path, _GENERIC_READ | _SYNCHRONIZE, os.O_RDONLY)
401 def open_for_delete_without_oplock_wait(path: str) -> int:
402 """
403 Open *path* with delete access and return a descriptor, without waiting for an oplock holder to answer.
405 The open handle shares read, write and delete, so a rename of *path* can proceed while the caller keeps it.
406 A holder that took an oplock through another handle is asked to answer by this open, which then raises, so the
407 caller skips the rename instead of waiting for it.
409 :param path: the file to rename.
411 :returns: a file descriptor owning the handle; the caller closes it.
413 :raises BlockingIOError: if an oplock break is in progress, which callers treat as contention.
414 :raises FileNotFoundError: if *path* does not exist.
415 :raises OSError: if the open fails for any other reason, or *path* is a reparse point.
417 """
418 return _open_existing_without_oplock_wait(path, _DELETE | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE, os.O_RDONLY)
420 def unlink_without_oplock_wait(path: str) -> None:
421 """
422 Delete *path* through a handle that does not wait for an oplock holder to answer its break.
424 ``os.unlink`` waits like ``os.open`` does. Here an unanswered break leaves the file in place, which callers
425 accept since deleting a lock file is best effort. A symlink at *path* is deleted as a link.
427 :param path: the file to delete.
429 :raises FileNotFoundError: if *path* does not exist.
430 :raises OSError: if the open fails for any other reason, such as a sharing violation.
432 """
433 sys.audit("os.remove", path, None)
434 handle, status = _nt_create(
435 path,
436 _DELETE | _SYNCHRONIZE,
437 _FILE_ATTRIBUTE_NORMAL,
438 _FILE_SHARE_ALL,
439 _FILE_OPEN,
440 options=_CREATE_OPTIONS | _FILE_DELETE_ON_CLOSE,
441 )
442 if status == _STATUS_SUCCESS:
443 _kernel32.CloseHandle(handle) # deletes the file
444 elif status != _STATUS_OPLOCK_BREAK_IN_PROGRESS:
445 raise _status_error(status, path)
447 def _open_existing_without_oplock_wait(path: str, access: int, flags: int) -> int:
448 handle, status = _nt_create(path, access, _FILE_ATTRIBUTE_NORMAL, _FILE_SHARE_ALL, _FILE_OPEN)
449 if status != _STATUS_SUCCESS:
450 raise _status_error(status, path)
451 return _descriptor_for_non_reparse(handle, path, flags)
453 def _status_error(status: int, path: str) -> OSError:
454 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
455 return BlockingIOError(EWOULDBLOCK, "oplock break in progress", path)
456 if status in {_STATUS_OBJECT_NAME_NOT_FOUND, _STATUS_OBJECT_PATH_NOT_FOUND}:
457 return FileNotFoundError(ENOENT, os.strerror(ENOENT), path)
458 winerror = _ntdll.RtlNtStatusToDosError(status)
459 return OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
461 def _descriptor_for_non_reparse(handle: int, path: str, flags: int) -> int:
462 info = _BY_HANDLE_FILE_INFORMATION()
463 # Querying an open handle we just created does not fail.
464 if not _kernel32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover
465 err = ctypes.get_last_error()
466 _kernel32.CloseHandle(handle)
467 raise ctypes.WinError(err)
468 if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
469 _kernel32.CloseHandle(handle)
470 msg = f"Lock file is a reparse point (symlink/junction): {path}"
471 raise OSError(msg)
473 try:
474 # O_NOINHERIT mirrors os.open on Windows: the lock fd must not leak into child processes.
475 return msvcrt.open_osfhandle(handle, flags | os.O_NOINHERIT)
476 except BaseException: # pragma: no cover # open_osfhandle audits too; a hook raising must not leak the handle
477 _kernel32.CloseHandle(handle)
478 raise
480 def _open_deletable_for_reading(path: str) -> int:
481 """
482 Open *path* read-only without blocking a concurrent unlink and without following a reparse point.
484 ``os.open`` omits ``FILE_SHARE_DELETE``, so while a process has a file open that way, a delete of it fails with
485 a sharing violation. Every contender reads a strict claim and its owner unlinks it, so a reader that keeps the
486 claim open past the owner's retries makes the release fail.
487 """
488 sys.audit("open", path, None, os.O_RDONLY)
489 handle, status = _nt_create(path, _GENERIC_READ | _SYNCHRONIZE, 0, _FILE_SHARE_ALL, _FILE_OPEN)
490 if status != _STATUS_SUCCESS:
491 winerror = _ntdll.RtlNtStatusToDosError(status)
492 raise OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
493 try:
494 return msvcrt.open_osfhandle(handle, os.O_RDONLY | os.O_NOINHERIT)
495 except BaseException: # pragma: no cover # open_osfhandle audits too; a hook raising must not leak the handle
496 _kernel32.CloseHandle(handle)
497 raise
499 def _pin_directory(path: str) -> int:
500 """
501 Open the directory at *path* so that no process can rename or remove it until :func:`_unpin_directory`.
503 Windows has no ``dir_fd``, so an operation resolves every path component by name again. A handle on each
504 directory of a record path, opened without following a reparse point, keeps that name bound to the directory
505 checked here until the operation ends.
507 :raises NotADirectoryError: when *path* is a junction, a symlink or anything other than a directory.
508 """
509 sys.audit("open", path, None, os.O_RDONLY)
510 # GetFileInformationByHandle needs FILE_READ_ATTRIBUTES; listing access is what takes part in share checks.
511 access = _FILE_LIST_DIRECTORY | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE
512 handle, status = _nt_create(path, access, 0, _FILE_SHARE_READ_WRITE, _FILE_OPEN, _DIRECTORY_OPTIONS)
513 if status != _STATUS_SUCCESS:
514 winerror = _ntdll.RtlNtStatusToDosError(status)
515 raise OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
516 info = _BY_HANDLE_FILE_INFORMATION()
517 # Querying an open handle we just created does not fail.
518 if not _kernel32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover
519 error = ctypes.get_last_error()
520 _kernel32.CloseHandle(handle)
521 raise ctypes.WinError(error)
522 if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
523 _kernel32.CloseHandle(handle)
524 raise NotADirectoryError(ENOTDIR, "is a junction or symlink, not a directory", path)
525 return handle
527 def _unpin_directory(handle: int) -> None:
528 _kernel32.CloseHandle(handle)
530 def _is_unlinked(path: str) -> bool:
531 """
532 Report whether *path* is gone or pending deletion, which ``os.open`` reports as the same EACCES as a denial.
534 NTFS keeps an unlinked name listed, refusing every open with ``STATUS_DELETE_PENDING``, until the last handle
535 to the file closes. Another process holding such a handle, such as an antivirus scan, can keep it that way for
536 longer than any retry grace, yet the name's owner has already removed it.
537 """
538 handle, status = _nt_create(path, _FILE_READ_ATTRIBUTES | _SYNCHRONIZE, 0, _FILE_SHARE_ALL, _FILE_OPEN)
539 if handle:
540 _kernel32.CloseHandle(handle)
541 return status in {_STATUS_OBJECT_NAME_NOT_FOUND, _STATUS_DELETE_PENDING}
543 def _nt_open(path: str, *, read_only: bool, owner_only: bool) -> tuple[int, int]:
544 """
545 Open or create *path* for locking through ``NtCreateFile`` and return ``(handle, status)``.
547 Without *owner_only* a file this call creates gets no DACL of its own and inherits its directory's ACL.
548 """
549 attributes = _FILE_ATTRIBUTE_READONLY if read_only else _FILE_ATTRIBUTE_NORMAL
550 descriptor = _owner_only_descriptor() if owner_only else None
551 return _nt_create(
552 path, _DESIRED_ACCESS, attributes, _FILE_SHARE_READ_WRITE, _FILE_OPEN_IF, descriptor=descriptor
553 )
555 @cache
556 def _owner_only_descriptor() -> ctypes.c_void_p:
557 # The DACL os.mkdir(mode=0o700) applies, minus the directory-only inheritance flags: protected (P), so the
558 # directory's inheritable entries stay out, with full access (FA) for SYSTEM, Administrators and the owner.
559 # Converted once and never freed: the open retries every few milliseconds while it waits.
560 descriptor = ctypes.c_void_p()
561 if not _advapi32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
562 "D:P(A;;FA;;;SY)(A;;FA;;;BA)(A;;FA;;;OW)", 1, ctypes.byref(descriptor), None
563 ): # pragma: no cover # a constant string converts
564 raise ctypes.WinError(ctypes.get_last_error())
565 return descriptor
567 def _nt_create( # ruff:ignore[too-many-arguments, too-many-positional-arguments] # NtCreateFile's own knobs
568 path: str,
569 access: int,
570 attributes: int,
571 share: int,
572 disposition: int,
573 options: int = _CREATE_OPTIONS,
574 *,
575 descriptor: ctypes.c_void_p | None = None,
576 ) -> tuple[int, int]:
577 """
578 Open *path* through ``NtCreateFile`` and return ``(handle, status)``.
580 ``RtlDosPathNameToNtPathName_U_WithStatus`` translates the Win32 path to the NT namespace, handling relative,
581 drive, UNC and extended-length path forms as Win32 itself would, and allocates a buffer that
582 ``RtlFreeUnicodeString`` releases. The handle is ``0`` unless the status is ``STATUS_SUCCESS``: one that comes
583 with ``STATUS_OPLOCK_BREAK_IN_PROGRESS`` is closed here, since the file is not ours until the oplock holder
584 answers.
585 """
586 nt_name = _UNICODE_STRING()
587 status = _ntdll.RtlDosPathNameToNtPathName_U_WithStatus(path, ctypes.byref(nt_name), None, None) & 0xFFFFFFFF
588 if status != _STATUS_SUCCESS:
589 return 0, status
590 try:
591 object_attributes = _OBJECT_ATTRIBUTES()
592 object_attributes.Length = ctypes.sizeof(_OBJECT_ATTRIBUTES)
593 object_attributes.ObjectName = ctypes.pointer(nt_name)
594 object_attributes.Attributes = _OBJ_CASE_INSENSITIVE
595 object_attributes.SecurityDescriptor = descriptor
596 handle = wintypes.HANDLE()
597 io_status = _IO_STATUS_BLOCK()
598 status = (
599 _ntdll.NtCreateFile(
600 ctypes.byref(handle),
601 access,
602 ctypes.byref(object_attributes),
603 ctypes.byref(io_status),
604 None,
605 attributes,
606 share,
607 disposition,
608 options,
609 None,
610 0,
611 )
612 & 0xFFFFFFFF
613 )
614 finally:
615 _ntdll.RtlFreeUnicodeString(ctypes.byref(nt_name))
616 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
617 _kernel32.CloseHandle(handle)
618 if status != _STATUS_SUCCESS:
619 return 0, status
620 return handle.value or 0, status
622 def _directory_is_private(path: str) -> bool:
623 """
624 Report whether only the current user, ``SYSTEM`` and ``Administrators`` can create or remove names in *path*.
626 A directory whose owner is anyone else can have its ACL rewritten by that owner. Entries that only a child
627 inherits count too, since the DACL says nothing more precise about who may write.
628 """
629 owner, dacl, descriptor = ctypes.c_void_p(), ctypes.c_void_p(), ctypes.c_void_p()
630 error = _advapi32.GetNamedSecurityInfoW(
631 path,
632 1, # SE_FILE_OBJECT
633 0x1 | 0x4, # OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION
634 ctypes.byref(owner),
635 None,
636 ctypes.byref(dacl),
637 None,
638 ctypes.byref(descriptor),
639 )
640 if error == _ERROR_ACCESS_DENIED:
641 # C:\Windows\Temp is one. Anything that cannot be proven private is not.
642 return False
643 if error: # pragma: no cover # the directory was opened or listed an instant earlier
644 raise ctypes.WinError(error)
645 try:
646 # SYSTEM, Administrators, CREATOR OWNER and OWNER RIGHTS; the last two stand for the owner.
647 trusted = {_sid_from_text(text) for text in ("S-1-5-18", "S-1-5-32-544", "S-1-3-0", "S-1-3-4")}
648 trusted.add(_user_sid())
649 # A missing DACL grants everyone full access.
650 return (
651 bool(dacl.value)
652 and _sid_at(cast("int", owner.value)) in trusted
653 and _name_writers(cast("int", dacl.value)) <= trusted
654 )
655 finally:
656 _kernel32.LocalFree(descriptor)
658 def _name_writers(dacl: int) -> set[bytes]:
659 (count,) = struct.unpack("<4xH2x", ctypes.string_at(dacl, 8))
660 writers = set()
661 offset = 8
662 for _ in range(count):
663 ace_type, _flags, ace_size, mask = struct.unpack("<BBHI", ctypes.string_at(dacl + offset, 8))
664 # Allowed and allowed-callback ACEs share a layout; object ACEs exist only in directory services. The check
665 # is conservative: any right that can turn into creating a name counts, namely FILE_ADD_FILE,
666 # FILE_ADD_SUBDIRECTORY, FILE_DELETE_CHILD, WRITE_DAC, WRITE_OWNER, GENERIC_WRITE and GENERIC_ALL.
667 if ace_type in {0, 9} and mask & (0x2 | 0x4 | 0x40 | 0x40000 | 0x80000 | 0x40000000 | 0x10000000):
668 writers.add(_sid_at(dacl + offset + 8))
669 offset += ace_size
670 return writers
672 def _user_sid() -> bytes:
673 token = wintypes.HANDLE()
674 token_query: Final = 0x0008
675 open_as_self: Final = True
676 # An impersonating thread acts as the account it impersonates, which is the one whose names the lock creates.
677 if not (
678 _advapi32.OpenThreadToken(_kernel32.GetCurrentThread(), token_query, open_as_self, ctypes.byref(token))
679 or _advapi32.OpenProcessToken(_kernel32.GetCurrentProcess(), token_query, ctypes.byref(token))
680 ): # pragma: no cover # every process may query its own token
681 raise ctypes.WinError(ctypes.get_last_error())
682 try:
683 size = wintypes.DWORD()
684 _advapi32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
685 buffer = ctypes.create_string_buffer(size.value)
686 if not _advapi32.GetTokenInformation(
687 token, 1, buffer, size, ctypes.byref(size)
688 ): # pragma: no cover # the buffer has the size the first call asked for
689 raise ctypes.WinError(ctypes.get_last_error())
690 return _sid_at(cast("int", ctypes.c_void_p.from_buffer(buffer).value))
691 finally:
692 _kernel32.CloseHandle(token)
694 def _sid_from_text(text: str) -> bytes:
695 revision, authority, *subauthorities = (int(part) for part in text.removeprefix("S-").split("-"))
696 return (
697 struct.pack("<BB", revision, len(subauthorities))
698 + authority.to_bytes(6, "big")
699 + struct.pack(f"<{len(subauthorities)}I", *subauthorities)
700 )
702 def _sid_at(address: int) -> bytes:
703 return ctypes.string_at(address, 8 + 4 * ctypes.string_at(address + 1, 1)[0])
705 def _make_private_directory(path: str) -> None:
706 """Create *path* with the owner-only descriptor, so that nobody else can add a name to it."""
707 attributes = _SECURITY_ATTRIBUTES(
708 nLength=ctypes.sizeof(_SECURITY_ATTRIBUTES),
709 lpSecurityDescriptor=_owner_only_descriptor(),
710 bInheritHandle=False,
711 )
712 if not _kernel32.CreateDirectoryW(path, ctypes.byref(attributes)): # pragma: no cover # the name is fresh
713 raise ctypes.WinError(ctypes.get_last_error())
715 @contextmanager
716 def _pinned(path: str) -> Generator[tuple[int, int]]:
717 """Hold *path* open without delete sharing, which keeps its name from being renamed or removed."""
718 with _opened(path, _FILE_SHARE_READ_WRITE) as handle:
719 yield _identity_of(handle)
721 def _identity_at(path: str) -> tuple[int, int]:
722 with _opened(path, _FILE_SHARE_ALL) as handle:
723 return _identity_of(handle)
725 def _identity_of_fd(fd: int) -> tuple[int, int]:
726 return _identity_of(msvcrt.get_osfhandle(fd))
728 @contextmanager
729 def _opened(path: str, share: int) -> Generator[int]:
730 # The final component is opened as itself, never through a reparse point.
731 handle = _kernel32.CreateFileW(
732 path,
733 _FILE_READ_ATTRIBUTES,
734 share,
735 None,
736 3, # OPEN_EXISTING
737 0x02000000 | 0x00200000, # FILE_FLAG_BACKUP_SEMANTICS opens a directory; FILE_FLAG_OPEN_REPARSE_POINT
738 None,
739 )
740 if handle in {None, _INVALID_HANDLE_VALUE}: # pragma: no cover # callers open a name they just made or listed
741 raise ctypes.WinError(ctypes.get_last_error())
742 try:
743 yield cast("int", handle)
744 finally:
745 _kernel32.CloseHandle(handle)
747 def _identity_of(handle: int) -> tuple[int, int]:
748 info = _BY_HANDLE_FILE_INFORMATION()
749 if not _kernel32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover
750 raise ctypes.WinError(ctypes.get_last_error())
751 return info.dwVolumeSerialNumber, info.nFileIndexHigh << 32 | info.nFileIndexLow
753else: # pragma: win32 no cover
755 class WindowsFileLock(BaseFileLock):
756 """Uses ``LockFileEx`` to hard lock a byte range of the lock file on Windows systems."""
758 def _acquire(self) -> None:
759 raise NotImplementedError
761 def _release(self) -> None:
762 raise NotImplementedError
765__all__ = [
766 "WindowsFileLock",
767 "_directory_is_private",
768 "_identity_at",
769 "_identity_of_fd",
770 "_is_unlinked",
771 "_make_private_directory",
772 "_open_deletable_for_reading",
773 "_open_non_reparse_fd",
774 "_pin_directory",
775 "_pinned",
776 "_unpin_directory",
777 "open_for_delete_without_oplock_wait",
778 "open_read_without_oplock_wait",
779 "unlink_without_oplock_wait",
780]