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 # Open *path* for locking while refusing reparse points, bound to the handle actually locked.
317 #
318 # The file is opened through ``NtCreateFile`` with ``FILE_OPEN_REPARSE_POINT`` so a symlink or junction planted
319 # at the path is not followed, and the reparse decision is read from *that* handle via
320 # ``GetFileInformationByHandle`` rather than from a prior pathname query. Reading the held handle closes the
321 # check-then-open race: an attacker cannot swap the path between validation and use because both act on the same
322 # handle. Share mode omits delete so a peer cannot unlink or rename the file out from under a live holder,
323 # matching ``os.open``'s ``_SH_DENYNO``.
324 #
325 # ``NtCreateFile`` is used instead of ``CreateFileW`` because its return value carries the raw ``NTSTATUS``.
326 # Windows collapses a transient delete-pending name and a permanent access denial into the same Win32
327 # ``ERROR_ACCESS_DENIED``; the status keeps them apart, so a real denial fails fast instead of spinning until
328 # the caller's timeout (#604).
329 #
330 # The reparse option only guards the final path component; Windows still follows reparse points in intermediate
331 # directories. This assumes the lock file sits in a lock directory untrusted users cannot modify. A path with
332 # attacker-controlled parent directories would need component-by-component handle validation.
333 #
334 # :param path: the lock file path.
335 # :param mode: the permission mode; as ``os.open`` does on Windows, a cleared owner-write bit creates the file
336 # read-only. A mode without group and other bits creates it with an owner-only DACL (discretionary access
337 # control list, the Windows permission list); any other mode has no Windows counterpart and leaves the file
338 # the entries its directory hands down. Both only take effect when the file is created, not when an existing
339 # one is opened.
340 #
341 # :param oplock_wait: seconds to wait for the holder of an oplock on the file to answer its break.
342 #
343 # :returns: a file descriptor owning the opened handle, or ``None`` on a sharing violation or a delete-pending
344 # name, which the caller should treat as contention and retry.
345 #
346 # :raises BlockingIOError: if an oplock break stays unanswered for *oplock_wait* seconds.
347 # :raises OSError: if the path resolves to a reparse point, or the open fails for any other reason, raised with
348 # the Win32 error the status maps to. An access denial is raised only once it outlasts a run of probes,
349 # since a peer unlinking the file as it releases can make the open answer ``STATUS_ACCESS_DENIED`` for a
350 # moment.
351 # Emit the audit event os.open would, so consumers watching "open" still see the path-level open and can veto.
352 sys.audit("open", path, None, os.O_RDWR | os.O_CREAT)
353 read_only = not mode & _OWNER_WRITE
354 owner_only = not mode & 0o077
355 handle, status = _nt_open(path, read_only=read_only, owner_only=owner_only)
356 oplock_deadline = time.monotonic() + oplock_wait
357 denied_probes = 0
358 while True:
359 if status == _STATUS_ACCESS_DENIED:
360 if denied_probes >= _ACCESS_DENIED_PROBES:
361 break
362 denied_probes += 1
363 elif status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
364 if time.monotonic() >= oplock_deadline:
365 break
366 else:
367 break
368 time.sleep(_ACCESS_DENIED_RETRY)
369 handle, status = _nt_open(path, read_only=read_only, owner_only=owner_only)
370 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
371 msg = "oplock break in progress"
372 raise BlockingIOError(EWOULDBLOCK, msg, path)
373 if status != _STATUS_SUCCESS:
374 if status in {_STATUS_SHARING_VIOLATION, _STATUS_DELETE_PENDING}:
375 return None
376 raise _status_error(status, path)
378 return _descriptor_for_non_reparse(handle, path, os.O_RDWR)
380 def open_read_without_oplock_wait(path: str) -> int:
381 # Open *path* read-only and return a descriptor, without waiting for an oplock holder to answer its break.
382 #
383 # ``os.open`` waits inside the system call until the holder of an oplock on the file answers or closes its
384 # handle, so no timeout or ``blocking=False`` ends the wait. A reparse point at *path* is refused rather than
385 # followed.
386 #
387 # :param path: the file to read.
388 #
389 # :returns: a read-only file descriptor.
390 #
391 # :raises BlockingIOError: if an oplock break is in progress, which callers treat as contention.
392 # :raises FileNotFoundError: if *path* does not exist.
393 # :raises OSError: if the open fails for any other reason, or *path* is a reparse point.
394 sys.audit("open", path, None, os.O_RDONLY)
395 return _open_existing_without_oplock_wait(path, _GENERIC_READ | _SYNCHRONIZE, os.O_RDONLY)
397 def open_for_delete_without_oplock_wait(path: str) -> int:
398 # Open *path* with delete access and return a descriptor, without waiting for an oplock holder to answer.
399 #
400 # The open handle shares read, write and delete, so a rename of *path* can proceed while the caller keeps it.
401 # A holder that took an oplock through another handle is asked to answer by this open, which then raises, so the
402 # caller skips the rename instead of waiting for it.
403 #
404 # :param path: the file to rename.
405 #
406 # :returns: a file descriptor owning the handle; the caller closes it.
407 #
408 # :raises BlockingIOError: if an oplock break is in progress, which callers treat as contention.
409 # :raises FileNotFoundError: if *path* does not exist.
410 # :raises OSError: if the open fails for any other reason, or *path* is a reparse point.
411 return _open_existing_without_oplock_wait(path, _DELETE | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE, os.O_RDONLY)
413 def unlink_without_oplock_wait(path: str) -> None:
414 # Delete *path* through a handle that does not wait for an oplock holder to answer its break.
415 #
416 # ``os.unlink`` waits like ``os.open`` does. Here an unanswered break leaves the file in place, which callers
417 # accept since deleting a lock file is best effort. A symlink at *path* is deleted as a link.
418 #
419 # :param path: the file to delete.
420 #
421 # :raises FileNotFoundError: if *path* does not exist.
422 # :raises OSError: if the open fails for any other reason, such as a sharing violation.
423 sys.audit("os.remove", path, None)
424 handle, status = _nt_create(
425 path,
426 _DELETE | _SYNCHRONIZE,
427 _FILE_ATTRIBUTE_NORMAL,
428 _FILE_SHARE_ALL,
429 _FILE_OPEN,
430 options=_CREATE_OPTIONS | _FILE_DELETE_ON_CLOSE,
431 )
432 if status == _STATUS_SUCCESS:
433 _KERNEL32.CloseHandle(handle) # deletes the file
434 elif status != _STATUS_OPLOCK_BREAK_IN_PROGRESS:
435 raise _status_error(status, path)
437 def _open_existing_without_oplock_wait(path: str, access: int, flags: int) -> int:
438 handle, status = _nt_create(path, access, _FILE_ATTRIBUTE_NORMAL, _FILE_SHARE_ALL, _FILE_OPEN)
439 if status != _STATUS_SUCCESS:
440 raise _status_error(status, path)
441 return _descriptor_for_non_reparse(handle, path, flags)
443 def _status_error(status: int, path: str) -> OSError:
444 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
445 return BlockingIOError(EWOULDBLOCK, "oplock break in progress", path)
446 if status in {_STATUS_OBJECT_NAME_NOT_FOUND, _STATUS_OBJECT_PATH_NOT_FOUND}:
447 return FileNotFoundError(ENOENT, os.strerror(ENOENT), path)
448 winerror = _NTDLL.RtlNtStatusToDosError(status)
449 return OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
451 def _descriptor_for_non_reparse(handle: int, path: str, flags: int) -> int:
452 info = _BY_HANDLE_FILE_INFORMATION()
453 # Querying an open handle we just created does not fail.
454 if not _KERNEL32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover
455 err = ctypes.get_last_error()
456 _KERNEL32.CloseHandle(handle)
457 raise ctypes.WinError(err)
458 if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
459 _KERNEL32.CloseHandle(handle)
460 msg = f"Lock file is a reparse point (symlink/junction): {path}"
461 raise OSError(msg)
463 try:
464 # O_NOINHERIT mirrors os.open on Windows: the lock fd must not leak into child processes.
465 return msvcrt.open_osfhandle(handle, flags | os.O_NOINHERIT)
466 except BaseException: # pragma: no cover # open_osfhandle audits too; a hook raising must not leak the handle
467 _KERNEL32.CloseHandle(handle)
468 raise
470 def _open_deletable_for_reading(path: str) -> int:
471 # Open *path* read-only without blocking a concurrent unlink and without following a reparse point.
472 #
473 # ``os.open`` omits ``FILE_SHARE_DELETE``, so while a process has a file open that way, a delete of it fails
474 # with a sharing violation. Every contender reads a strict claim and its owner unlinks it, so a reader that
475 # keeps the claim open past the owner's retries makes the release fail.
476 sys.audit("open", path, None, os.O_RDONLY)
477 handle, status = _nt_create(path, _GENERIC_READ | _SYNCHRONIZE, 0, _FILE_SHARE_ALL, _FILE_OPEN)
478 if status != _STATUS_SUCCESS:
479 winerror = _NTDLL.RtlNtStatusToDosError(status)
480 raise OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
481 try:
482 return msvcrt.open_osfhandle(handle, os.O_RDONLY | os.O_NOINHERIT)
483 except BaseException: # pragma: no cover # open_osfhandle audits too; a hook raising must not leak the handle
484 _KERNEL32.CloseHandle(handle)
485 raise
487 def _pin_directory(path: str) -> int:
488 # Open the directory at *path* so that no process can rename or remove it until :func:`_unpin_directory`.
489 #
490 # Windows has no ``dir_fd``, so an operation resolves every path component by name again. A handle on each
491 # directory of a record path, opened without following a reparse point, keeps that name bound to the directory
492 # checked here until the operation ends.
493 #
494 # :raises NotADirectoryError: when *path* is a junction, a symlink or anything other than a directory.
495 sys.audit("open", path, None, os.O_RDONLY)
496 # GetFileInformationByHandle needs FILE_READ_ATTRIBUTES; listing access is what takes part in share checks.
497 access = _FILE_LIST_DIRECTORY | _FILE_READ_ATTRIBUTES | _SYNCHRONIZE
498 handle, status = _nt_create(path, access, 0, _FILE_SHARE_READ_WRITE, _FILE_OPEN, _DIRECTORY_OPTIONS)
499 if status != _STATUS_SUCCESS:
500 winerror = _NTDLL.RtlNtStatusToDosError(status)
501 raise OSError(None, ctypes.FormatError(winerror).strip(), path, winerror)
502 info = _BY_HANDLE_FILE_INFORMATION()
503 # Querying an open handle we just created does not fail.
504 if not _KERNEL32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover
505 error = ctypes.get_last_error()
506 _KERNEL32.CloseHandle(handle)
507 raise ctypes.WinError(error)
508 if info.dwFileAttributes & _FILE_ATTRIBUTE_REPARSE_POINT:
509 _KERNEL32.CloseHandle(handle)
510 raise NotADirectoryError(ENOTDIR, "is a junction or symlink, not a directory", path)
511 return handle
513 def _unpin_directory(handle: int) -> None:
514 _KERNEL32.CloseHandle(handle)
516 def _is_unlinked(path: str) -> bool:
517 # Report whether *path* is gone or pending deletion, which ``os.open`` reports as the same EACCES as a denial.
518 #
519 # NTFS keeps an unlinked name listed, refusing every open with ``STATUS_DELETE_PENDING``, until the last handle
520 # to the file closes. Another process holding such a handle, such as an antivirus scan, can keep it that way for
521 # longer than any retry grace, yet the name's owner has already removed it.
522 handle, status = _nt_create(path, _FILE_READ_ATTRIBUTES | _SYNCHRONIZE, 0, _FILE_SHARE_ALL, _FILE_OPEN)
523 if handle:
524 _KERNEL32.CloseHandle(handle)
525 return status in {_STATUS_OBJECT_NAME_NOT_FOUND, _STATUS_DELETE_PENDING}
527 def _nt_open(path: str, *, read_only: bool, owner_only: bool) -> tuple[int, int]:
528 # Open or create *path* for locking through ``NtCreateFile`` and return ``(handle, status)``.
529 #
530 # Without *owner_only* a file this call creates gets no DACL of its own and inherits its directory's ACL.
531 attributes = _FILE_ATTRIBUTE_READONLY if read_only else _FILE_ATTRIBUTE_NORMAL
532 descriptor = _owner_only_descriptor() if owner_only else None
533 return _nt_create(
534 path, _DESIRED_ACCESS, attributes, _FILE_SHARE_READ_WRITE, _FILE_OPEN_IF, descriptor=descriptor
535 )
537 @cache
538 def _owner_only_descriptor() -> ctypes.c_void_p:
539 # The DACL os.mkdir(mode=0o700) applies, minus the directory-only inheritance flags: protected (P), so the
540 # directory's inheritable entries stay out, with full access (FA) for SYSTEM, Administrators and the owner.
541 # Converted once and never freed: the open retries every few milliseconds while it waits.
542 descriptor = ctypes.c_void_p()
543 if not _ADVAPI32.ConvertStringSecurityDescriptorToSecurityDescriptorW(
544 "D:P(A;;FA;;;SY)(A;;FA;;;BA)(A;;FA;;;OW)", 1, ctypes.byref(descriptor), None
545 ): # pragma: no cover # a constant string converts
546 raise ctypes.WinError(ctypes.get_last_error())
547 return descriptor
549 def _nt_create( # ruff:ignore[too-many-arguments, too-many-positional-arguments] # NtCreateFile's own knobs
550 path: str,
551 access: int,
552 attributes: int,
553 share: int,
554 disposition: int,
555 options: int = _CREATE_OPTIONS,
556 *,
557 descriptor: ctypes.c_void_p | None = None,
558 ) -> tuple[int, int]:
559 # Open *path* through ``NtCreateFile`` and return ``(handle, status)``.
560 #
561 # ``RtlDosPathNameToNtPathName_U_WithStatus`` translates the Win32 path to the NT namespace, handling relative,
562 # drive, UNC and extended-length path forms as Win32 itself would, and allocates a buffer that
563 # ``RtlFreeUnicodeString`` releases. The handle is ``0`` unless the status is ``STATUS_SUCCESS``: one that comes
564 # with ``STATUS_OPLOCK_BREAK_IN_PROGRESS`` is closed here, since the file is not ours until the oplock holder
565 # answers.
566 nt_name = _UNICODE_STRING()
567 status = _NTDLL.RtlDosPathNameToNtPathName_U_WithStatus(path, ctypes.byref(nt_name), None, None) & 0xFFFFFFFF
568 if status != _STATUS_SUCCESS:
569 return 0, status
570 try:
571 object_attributes = _OBJECT_ATTRIBUTES()
572 object_attributes.Length = ctypes.sizeof(_OBJECT_ATTRIBUTES)
573 object_attributes.ObjectName = ctypes.pointer(nt_name)
574 object_attributes.Attributes = _OBJ_CASE_INSENSITIVE
575 object_attributes.SecurityDescriptor = descriptor
576 handle = wintypes.HANDLE()
577 io_status = _IO_STATUS_BLOCK()
578 status = (
579 _NTDLL.NtCreateFile(
580 ctypes.byref(handle),
581 access,
582 ctypes.byref(object_attributes),
583 ctypes.byref(io_status),
584 None,
585 attributes,
586 share,
587 disposition,
588 options,
589 None,
590 0,
591 )
592 & 0xFFFFFFFF
593 )
594 finally:
595 _NTDLL.RtlFreeUnicodeString(ctypes.byref(nt_name))
596 if status == _STATUS_OPLOCK_BREAK_IN_PROGRESS:
597 _KERNEL32.CloseHandle(handle)
598 if status != _STATUS_SUCCESS:
599 return 0, status
600 return handle.value or 0, status
602 def _directory_is_private(path: str) -> bool:
603 # Report whether only the current user, ``SYSTEM`` and ``Administrators`` can create or remove names in *path*.
604 #
605 # A directory whose owner is anyone else can have its ACL rewritten by that owner. Entries that only a child
606 # inherits count too, since the DACL says nothing more precise about who may write.
607 owner, dacl, descriptor = ctypes.c_void_p(), ctypes.c_void_p(), ctypes.c_void_p()
608 error = _ADVAPI32.GetNamedSecurityInfoW(
609 path,
610 1, # SE_FILE_OBJECT
611 0x1 | 0x4, # OWNER_SECURITY_INFORMATION | DACL_SECURITY_INFORMATION
612 ctypes.byref(owner),
613 None,
614 ctypes.byref(dacl),
615 None,
616 ctypes.byref(descriptor),
617 )
618 if error == _ERROR_ACCESS_DENIED:
619 # C:\Windows\Temp is one. Anything that cannot be proven private is not.
620 return False
621 if error: # pragma: no cover # the directory was opened or listed an instant earlier
622 raise ctypes.WinError(error)
623 try:
624 # SYSTEM, Administrators, CREATOR OWNER and OWNER RIGHTS; the last two stand for the owner.
625 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")}
626 trusted.add(_user_sid())
627 # A missing DACL grants everyone full access.
628 return (
629 bool(dacl.value)
630 and _sid_at(cast("int", owner.value)) in trusted
631 and _name_writers(cast("int", dacl.value)) <= trusted
632 )
633 finally:
634 _KERNEL32.LocalFree(descriptor)
636 def _name_writers(dacl: int) -> set[bytes]:
637 (count,) = struct.unpack("<4xH2x", ctypes.string_at(dacl, 8))
638 writers = set()
639 offset = 8
640 for _ in range(count):
641 ace_type, _flags, ace_size, mask = struct.unpack("<BBHI", ctypes.string_at(dacl + offset, 8))
642 # Allowed and allowed-callback ACEs share a layout; object ACEs exist only in directory services. The check
643 # is conservative: any right that can turn into creating a name counts, namely FILE_ADD_FILE,
644 # FILE_ADD_SUBDIRECTORY, FILE_DELETE_CHILD, WRITE_DAC, WRITE_OWNER, GENERIC_WRITE and GENERIC_ALL.
645 if ace_type in {0, 9} and mask & (0x2 | 0x4 | 0x40 | 0x40000 | 0x80000 | 0x40000000 | 0x10000000):
646 writers.add(_sid_at(dacl + offset + 8))
647 offset += ace_size
648 return writers
650 def _user_sid() -> bytes:
651 token = wintypes.HANDLE()
652 token_query: Final = 0x0008
653 open_as_self: Final = True
654 # An impersonating thread acts as the account it impersonates, which is the one whose names the lock creates.
655 if not (
656 _ADVAPI32.OpenThreadToken(_KERNEL32.GetCurrentThread(), token_query, open_as_self, ctypes.byref(token))
657 or _ADVAPI32.OpenProcessToken(_KERNEL32.GetCurrentProcess(), token_query, ctypes.byref(token))
658 ): # pragma: no cover # every process may query its own token
659 raise ctypes.WinError(ctypes.get_last_error())
660 try:
661 size = wintypes.DWORD()
662 _ADVAPI32.GetTokenInformation(token, 1, None, 0, ctypes.byref(size))
663 buffer = ctypes.create_string_buffer(size.value)
664 if not _ADVAPI32.GetTokenInformation(
665 token, 1, buffer, size, ctypes.byref(size)
666 ): # pragma: no cover # the buffer has the size the first call asked for
667 raise ctypes.WinError(ctypes.get_last_error())
668 return _sid_at(cast("int", ctypes.c_void_p.from_buffer(buffer).value))
669 finally:
670 _KERNEL32.CloseHandle(token)
672 def _sid_from_text(text: str) -> bytes:
673 revision, authority, *subauthorities = (int(part) for part in text.removeprefix("S-").split("-"))
674 return (
675 struct.pack("<BB", revision, len(subauthorities))
676 + authority.to_bytes(6, "big")
677 + struct.pack(f"<{len(subauthorities)}I", *subauthorities)
678 )
680 def _sid_at(address: int) -> bytes:
681 return ctypes.string_at(address, 8 + 4 * ctypes.string_at(address + 1, 1)[0])
683 def _make_private_directory(path: str) -> None:
684 # Create *path* with the owner-only descriptor, so that nobody else can add a name to it.
685 attributes = _SECURITY_ATTRIBUTES(
686 nLength=ctypes.sizeof(_SECURITY_ATTRIBUTES),
687 lpSecurityDescriptor=_owner_only_descriptor(),
688 bInheritHandle=False,
689 )
690 if not _KERNEL32.CreateDirectoryW(path, ctypes.byref(attributes)): # pragma: no cover # the name is fresh
691 raise ctypes.WinError(ctypes.get_last_error())
693 @contextmanager
694 def _pinned(path: str) -> Generator[tuple[int, int]]:
695 # Hold *path* open without delete sharing, which keeps its name from being renamed or removed.
696 with _opened(path, _FILE_SHARE_READ_WRITE) as handle:
697 yield _identity_of(handle)
699 def _identity_at(path: str) -> tuple[int, int]:
700 with _opened(path, _FILE_SHARE_ALL) as handle:
701 return _identity_of(handle)
703 def _identity_of_fd(fd: int) -> tuple[int, int]:
704 return _identity_of(msvcrt.get_osfhandle(fd))
706 @contextmanager
707 def _opened(path: str, share: int) -> Generator[int]:
708 # The final component is opened as itself, never through a reparse point.
709 handle = _KERNEL32.CreateFileW(
710 path,
711 _FILE_READ_ATTRIBUTES,
712 share,
713 None,
714 3, # OPEN_EXISTING
715 0x02000000 | 0x00200000, # FILE_FLAG_BACKUP_SEMANTICS opens a directory; FILE_FLAG_OPEN_REPARSE_POINT
716 None,
717 )
718 if handle in {None, _INVALID_HANDLE_VALUE}: # pragma: no cover # callers open a name they just made or listed
719 raise ctypes.WinError(ctypes.get_last_error())
720 try:
721 yield cast("int", handle)
722 finally:
723 _KERNEL32.CloseHandle(handle)
725 def _identity_of(handle: int) -> tuple[int, int]:
726 info = _BY_HANDLE_FILE_INFORMATION()
727 if not _KERNEL32.GetFileInformationByHandle(handle, ctypes.byref(info)): # pragma: no cover # API failure
728 raise ctypes.WinError(ctypes.get_last_error())
729 return info.dwVolumeSerialNumber, info.nFileIndexHigh << 32 | info.nFileIndexLow
731else: # pragma: win32 no cover
733 class WindowsFileLock(BaseFileLock):
734 """Uses ``LockFileEx`` to hard lock a byte range of the lock file on Windows systems."""
736 def _acquire(self) -> None:
737 raise NotImplementedError
739 def _release(self) -> None:
740 raise NotImplementedError
743__all__ = [
744 "WindowsFileLock",
745 "_directory_is_private",
746 "_identity_at",
747 "_identity_of_fd",
748 "_is_unlinked",
749 "_make_private_directory",
750 "_open_deletable_for_reading",
751 "_open_non_reparse_fd",
752 "_pin_directory",
753 "_pinned",
754 "_unpin_directory",
755 "open_for_delete_without_oplock_wait",
756 "open_read_without_oplock_wait",
757 "unlink_without_oplock_wait",
758]