mirror of
https://github.com/nim-lang/Nim.git
synced 2026-08-01 13:09:14 +00:00
00d8f66311
This PR implements `expandSymlink` on Windows with POSIX readlink semantics: it expands exactly one hop and returns the stored link target without resolving the full chain. The main design question was whether Windows symlink expansion should be built on path-finalization APIs such as `GetFinalPathNameByHandleW`, or on direct reparse-point inspection. Current `expandSymlink` is a single-hop "what target is stored in this link object?" operation and most of other ways to resolve symlinks on Windows actually try to answer the "final true file location" question in various slightly-incompatible ways. The full final-path resolution on Windows is substantially more complex than readlink and is planned as a follow-up. ## Implementation choice Implements Windows `expandSymlink` by: - opening the path with `FILE_FLAG_OPEN_REPARSE_POINT` - calling `DeviceIoControl(FSCTL_GET_REPARSE_POINT)` - parsing the reparse payload for `IO_REPARSE_TAG_SYMLINK` and `IO_REPARSE_TAG_MOUNT_POINT` - decoding the UTF-16 slice referenced by the payload - returning the stored target This is the right primitive for the API: - does not depend on whole-path finalization - works for both symlinks and junctions - matches the existing Linux behaviour `widestrs` changes allow using WideCString views without temporary allocations. Windows prohibits symlink creation without admin rights, so, unfortunately, the tests are conditionally skipped by default. Manually running `testament` in an admin console is required. ## Behaviour: - One hop only - Relative symlink targets are returned unchanged - Absolute Windows targets are converted from stored NT-style prefixes to usable Win32 forms when applicable - Non-links, malformed payloads, and unsupported reparse tags raise `OSError` ## Future work Path canonicalization, i.e. "final true file location". Which is, BTW, different from `absolutePath`, which works on paths only and doesn't hit the underlying FS. So this needs to be an API extension. I'd like to follow-up with this when I sort through the docs, for now you can resolve symlinks in a loop. --------- Co-authored-by: Andreas Rumpf <rumpf_a@web.de>
45 lines
1.8 KiB
Nim
45 lines
1.8 KiB
Nim
## This module implements symlink (symbolic link) handling.
|
|
|
|
## .. importdoc:: os.nim
|
|
|
|
from std/paths import Path, ReadDirEffect
|
|
|
|
from std/private/ossymlinks import symlinkExists, createSymlink, expandSymlink
|
|
|
|
proc symlinkExists*(link: Path): bool {.inline, tags: [ReadDirEffect], sideEffect.} =
|
|
## Returns true if the symlink `link` exists. Will return true
|
|
## regardless of whether the link points to a directory or file.
|
|
result = symlinkExists(link.string)
|
|
|
|
proc createSymlink*(src, dest: Path) {.inline.} =
|
|
## Create a symbolic link at `dest` which points to the item specified
|
|
## by `src`. On most operating systems, will fail if a link already exists.
|
|
##
|
|
## .. warning:: Some OS's (such as Microsoft Windows) restrict the creation
|
|
## of symlinks to root users (administrators) or users with developer mode enabled.
|
|
##
|
|
## See also:
|
|
## * `createHardlink proc`_
|
|
## * `expandSymlink proc`_
|
|
createSymlink(src.string, dest.string)
|
|
|
|
proc expandSymlink*(symlinkPath: Path): Path {.inline.} =
|
|
## Returns the stored target of the symbolic link `symlinkPath`.
|
|
##
|
|
## This expands exactly one level of indirection, like POSIX `readlink`.
|
|
## If the target is itself a symbolic link, it is returned as-is rather than
|
|
## being expanded further.
|
|
##
|
|
## On POSIX, raises `OSError` if `symlinkPath` is not a symbolic link or if
|
|
## the target cannot be read.
|
|
##
|
|
## On Windows, this supports symbolic links and junctions by reading the
|
|
## reparse point payload directly. Unsupported reparse tags raise `OSError`.
|
|
##
|
|
## On Nintendo Switch this is currently a noop: `symlinkPath` is simply
|
|
## returned, without checking whether it is actually a symbolic link.
|
|
##
|
|
## See also:
|
|
## * `createSymlink proc`_
|
|
result = Path(expandSymlink(symlinkPath.string))
|