base/path.jl - master - githubmirror/julia

base/path.jl
1 030 строк35 KB
Shuhei Kadowaki
path: Bind exception in `homedir(username)` (#62553)
30 июл 2026, 03:32
30 июл 2026, 03:323168541
# This file is a part of Julia. License is MIT: https://julialang.org/license

# NB: This file is `Core.eval`-uated into the (pre-existing) module Filesystem

import Base: StringVector, utf8units

export
    abspath,
    basename,
    dirname,
    expanduser,
    contractuser,
    homedir,
    isabspath,
    isdirpath,
    joinpath,
    normpath,
    realpath,
    relpath,
    splitdir,
    splitdrive,
    splitext,
    splitpath

if Sys.isunix()
    const path_separator    = "/"
    @inline isseparator(c::Char) = c === '/'
    @inline isseparator(c::UInt8) = c === UInt8('/')

    splitdrive(path::String) = ("",path)
elseif Sys.iswindows()
    const path_separator    = "\\"
    @inline isseparator(c::Char) = c === '/' || c === '\\'
    @inline isseparator(c::UInt8) = c === UInt8('/') || c === UInt8('\\')

    @inline isdriveletter(c::Char) = isascii(c) && isdriveletter(UInt8(c))
    @inline function isdriveletter(c::UInt8)
        UInt8('A') <= c <= UInt8('Z') ||
        UInt8('a') <= c <= UInt8('z')
    end

    function _split_longunc(s::String)::Tuple{String, String}
        # Long UNC path, e.g. `\\?\UNC\server\share`
        # Based on previous implementation matching with regex
        # S = raw"[\\/]"; N = raw"[^\\/]";
        # r"^$(S)$(S)\?$(S)UNC$(S)$(N)+$(S)$(N)+"sa

        if (ncodeunits(s) >= 11 &&
            isseparator(codeunit(s, 1)) &&
            isseparator(codeunit(s, 2)) &&
            codeunit(s, 3) === UInt8('?') &&
            isseparator(codeunit(s, 4)) &&
            codeunit(s, 5) === UInt8('U') &&
            codeunit(s, 6) === UInt8('N') &&
            codeunit(s, 7) === UInt8('C') &&
            isseparator(codeunit(s, 8))
        )
            # Ensure we have [sequence of non-separator] - single separator - [sequence of non-separator].
            # Since the prefix raw"\\?\UNC\" is always 8 codeunits, we start at index 9.
            i = findnext(isseparator, s, 9)
            if (!isnothing(i) &&
                i >= 10 && # implies !isseparator(s[9])
                ncodeunits(s) > i && # Need something after the separator
                !isseparator(codeunit(s, i+1)) # Consecutive separators does not count
            )
                # Stop just before next separator if it exists,
                # otherwise the whole string is a drive
                j = something(findnext(isseparator, s, i+1), lastindex(s)+1)
                return s[1:prevind(s, j)], s[j:end]
            end
        end
        return "", s
    end

    function _split_longdriveletter(s::String)::Tuple{String, String}
        # Long drive letter, e.g. `\\?\C:`
        # Based on implementation matching with regex
        # S = raw"[\\/]"; N = raw"[^\\/]"; drive = "$(N):";
        # r"$(S)$(S)\?$(S)$(drive)"sa
        if (ncodeunits(s) >= 6 &&
            isseparator(codeunit(s, 1)) &&
            isseparator(codeunit(s, 2)) &&
            codeunit(s, 3) === UInt8('?') &&
            isseparator(codeunit(s, 4)) &&
            !isseparator(codeunit(s, 5)) && # Any ascii char except separators passes as the drive letter
            codeunit(s, 6) == UInt8(':') # This effectively limits codeunit(s, 5) to ascii
        )
            return s[1:6], s[nextind(s, 6):end]
        end
        return "", s
    end

    function _split_uncpath(s::String)::Tuple{String, String}
        # UNC path, e.g. `\\server\share`
        # Based on previous implementation matching with regex
        # S = raw"[\\/]"; N = raw"[^\\/]";
        # r"$(S)$(S)$(N)+$(S)$(N)+"sa
        if (ncodeunits(s) >= 5 && # Not shorter than `\\a\b`
            isseparator(codeunit(s, 1)) &&
            isseparator(codeunit(s, 2))
        )
            # Ensure we have [sequence of non-separator] - single separator - [sequence of non-separator].
            # Since the prefix raw"\\" is always 2 codeunits, we start at index 3.
            i = findnext(isseparator, s, 3)
            if (!isnothing(i) &&
                i >= 4 && # implies !isseparator(s[3])
                ncodeunits(s) > i && # Need something after the separator
                !isseparator(codeunit(s, i+1)) # Consecutive separators does not count
            )
                # Stop just before next separator if it exists,
                # otherwise the whole string is a drive
                j = something(findnext(isseparator, s, i+1), lastindex(s)+1)
                return s[1:prevind(s, j)], s[j:end]
            end
        end
        return "", s
    end

    function splitdrive(path::String)::Tuple{String, String}
        if !isempty(path)
            # Fast return if path does not contain a drive
            if !isseparator(codeunit(path, 1)) && (codeunit(path, 1) < 0x80)
                # Drive letter, e.g. `C:`
                # Any ascii char except separators passes as the drive letter
                colonind = nextind(path, 1)
                if checkbounds(Bool, path, colonind) && path[colonind] === ':'
                    return path[1:colonind], path[colonind+1:end]
                end
            elseif ncodeunits(path) >= 2 && isseparator(codeunit(path, 2))
                # All other drive types must start with two separators

                # Long UNC path, e.g. `\\?\UNC\server\share`
                drive, rest = _split_longunc(path)
                !isempty(drive) && return drive, rest

                # Long drive letter, e.g. `\\?\C:`
                drive, rest = _split_longdriveletter(path)
                !isempty(drive) && return drive, rest

                # UNC path, e.g. `\\server\share`
                drive, rest = _split_uncpath(path)
                !isempty(drive) && return drive, rest
            end
        end

        return "", path
    end
else
    error("path primitives for this OS need to be defined")
end


"""
    splitdrive(path::AbstractString) -> (drive::AbstractString, path::AbstractString)

On Windows, split a path into the drive letter part and the path part. On Unix systems, the
first component is always the empty string.
"""
splitdrive(path::AbstractString)

# Average buffer size including null terminator for several filesystem operations.
# On Windows we use the MAX_PATH = 260 value on Win32.
const AVG_PATH = Sys.iswindows() ? 260 : 512

"""
    homedir()::String

Return the current user's home directory.

!!! note
    `homedir` determines the home directory via `libuv`'s `uv_os_homedir`. For details
    (for example on how to specify the home directory via environment variables), see the
    [`uv_os_homedir` documentation](http://docs.libuv.org/en/v1.x/misc.html#c.uv_os_homedir).

    homedir(username::AbstractString)::Union{String,Nothing}

Return the home directory for the given `username`, or `nothing` if the user does not exist.
On Unix, this performs a lookup via `getpwnam_r`. On Windows, the user's SID is resolved and
the profile path is read from the registry; if that fails, the profile directory is inferred
from the current user's home directory.

See also [`Sys.username`](@ref).
"""
function homedir()
    buf = Base.StringVector(AVG_PATH - 1) # space for null-terminator implied by StringVector
    sz = Base.RefValue{Csize_t}(length(buf) + 1) # total buffer size including null
    while true
        rc = ccall(:uv_os_homedir, Cint, (Ptr{UInt8}, Ptr{Csize_t}), buf, sz)
        if rc == 0
            resize!(buf, sz[])
            return String(buf)
        elseif rc == Base.UV_ENOBUFS
            resize!(buf, sz[] - 1) # space for null-terminator implied by StringVector
        else
            uv_error("homedir()", rc)
        end
    end
end

function isabspath(path::String)
    isempty(path) && return false
    # Paths starting with "/" are considered absolute also on windows
    # This captures e.g. UNC paths, but does not guarantee a valid path.
    # Also note that isabspath(x) does not imply !isempty(splitdrive(x)[1])
    isseparator(codeunit(path, 1) ) && return true

    @static if Sys.iswindows()
        # the letter before : in e.g. "C:\" must be a valid drive letter.
        # This differs from `splitdrive`, where any non-separator single codeunit char is
        # accepted.
        firstsep = findfirst(isseparator, codeunits(path))
        if (!isnothing(firstsep) &&
            firstsep >= 3 &&
            codeunit(path, firstsep-1) == UInt(':')
        )
            for b in codeunits(path)[1:firstsep-2]
                !isdriveletter(b) && return false
            end
            return true
        end
    end
    return false
end

"""
    isabspath(path::AbstractString)::Bool

Determine whether a path is absolute (begins at the root directory).

# Examples
```jldoctest
julia> isabspath("/home")
true

julia> isabspath("home")
false
```
"""
isabspath(path::AbstractString)

"""
    isdirpath(path::AbstractString)::Bool

Determine whether a path refers to a directory (for example, ends with a path separator).

# Examples
```jldoctest
julia> isdirpath("/home")
false

julia> isdirpath("/home/")
true
```
"""
function isdirpath(path::String)::Bool
    # Reimplements occursin(r"(?:^|/)\.{0,2}$"sa, splitdrive(path)[2])

    _, after_last_separator = _splitdir_nodrive("", splitdrive(path)[2])
    return after_last_separator in ("", ".", "..")
end

"""
    splitdir(path::AbstractString) -> (dir::AbstractString, file::AbstractString)

Split a path into a tuple of the directory name and file name.

# Examples
```jldoctest
julia> splitdir("/home/myuser")
("/home", "myuser")
```
"""
function splitdir(path::String)
    a, b = splitdrive(path)
    _splitdir_nodrive(a,b)
end

# Common splitdir functionality without splitdrive, needed for splitpath.
_splitdir_nodrive(path::String) = _splitdir_nodrive("", path)
function _splitdir_nodrive(drive::String, path::String)::Tuple{String, String}
    lastsepind = findlast(isseparator, path)

    isnothing(lastsepind) && return drive, path

    dir = path[1:something(findprev(!isseparator, path, lastsepind), 1)]
    tail = path[nextind(path, lastsepind):end]

    return drive * dir, tail
end

"""
    dirname(path::AbstractString)::String

Get the directory part of a path. Trailing characters ('/' or '\\') in the path are
counted as part of the path.

# Examples
```jldoctest
julia> dirname("/home/myuser")
"/home"

julia> dirname("/home/myuser/")
"/home/myuser"
```

See also [`basename`](@ref).
"""
dirname(path::AbstractString) = splitdir(path)[1]

"""
    basename(path::AbstractString)::String

Get the file name part of a path.

!!! note
    This function differs slightly from the Unix `basename` program, where trailing slashes are ignored,
    i.e. `\$ basename /foo/bar/` returns `bar`, whereas `basename` in Julia returns an empty string `""`.

# Examples
```jldoctest
julia> basename("/home/myuser/example.jl")
"example.jl"

julia> basename("/home/myuser/")
""
```

See also [`dirname`](@ref).
"""
basename(path::AbstractString) = splitdir(path)[2]

"""
    splitext(path::AbstractString) -> (path_without_extension::String, extension::String)

If the last component of a path contains one or more dots, split the path into everything before the
last dot and everything including and after the dot. Otherwise, return a tuple of the argument
unmodified and the empty string. "splitext" is short for "split extension".

# Examples
```jldoctest
julia> splitext("/home/myuser/example.jl")
("/home/myuser/example", ".jl")

julia> splitext("/home/myuser/example.tar.gz")
("/home/myuser/example.tar", ".gz")

julia> splitext("/home/my.user/example")
("/home/my.user/example", "")
```
"""
function splitext(path::String)::Tuple{String, String}
    drive, p = splitdrive(path)
    lastdot = findlast('.', p)
    if !isnothing(lastdot)
        # No separator after the last dot
        if isnothing(findnext(isseparator, p, lastdot))
            # No separator just before the last dot
            prev = prevind(p, lastdot)
            if checkbounds(Bool, p, prev)
                if !isseparator(p[prev])
                    return drive * p[1:prev], p[lastdot:end]
                end
            end
        end
    end

    return (path, "")
end

# NOTE: deprecated in 1.4
pathsep() = path_separator

"""
    splitpath(path::AbstractString)::Vector{String}

Split a file path into all its path components. This is the opposite of
`joinpath`. Returns an array of substrings, one for each directory or file in
the path, including the root directory if present.

!!! compat "Julia 1.1"
    This function requires at least Julia 1.1.

# Examples
```jldoctest
julia> splitpath("/home/myuser/example.jl")
4-element Vector{String}:
 "/"
 "home"
 "myuser"
 "example.jl"
```
"""
splitpath(p::AbstractString) = splitpath(String(p)::String)

function splitpath(p::String)
    drive, p = splitdrive(p)
    out = String[]
    isempty(p) && (pushfirst!(out,p))  # "" means the current directory.
    while !isempty(p)
        dir, base = _splitdir_nodrive(p)
        dir == p && (pushfirst!(out, dir); break)  # Reached root node.
        if !isempty(base)  # Skip trailing '/' in basename
            pushfirst!(out, base)
        end
        p = dir
    end
    if !isempty(drive)  # Tack the drive back on to the first element.
        out[1] = drive*out[1]  # Note that length(out) is always >= 1.
    end
    return out
end

if Sys.iswindows()

function joinpath(paths::Union{Tuple, AbstractVector})::String
    assertstring(x) = x isa AbstractString || throw(ArgumentError("path component is not a string: $(repr(x))"))

    isempty(paths) && throw(ArgumentError("collection of path components must be non-empty"))
    assertstring(paths[1])
    result_drive, result_path = splitdrive(paths[1])

    p_path = ""
    for i in firstindex(paths)+1:lastindex(paths)
        assertstring(paths[i])
        p_drive, p_path = splitdrive(paths[i])

        if !isempty(p_path) && isseparator(first(p_path))
            # second path is absolute
            if !isempty(p_drive) || !isempty(result_drive)
                result_drive = p_drive
            end
            result_path = p_path
            continue
        elseif !isempty(p_drive) && p_drive != result_drive
            if lowercase(p_drive) != lowercase(result_drive)
                # different drives, ignore the first path entirely
                result_drive = p_drive
                result_path = p_path
                continue
            end
        end

        # second path is relative to the first
        if !isempty(result_path) && !isseparator(result_path[end])
            result_path *= "\\"
        end

        result_path = result_path * p_path
    end

    # add separator between UNC and non-absolute path
    if (!isempty(p_path) &&
        !isseparator(result_path[1]) &&
        !isempty(result_drive) &&
        result_drive[end] != ':'
    )
        return result_drive * "\\" * result_path
    end

    return result_drive * result_path
end

else

function joinpath(paths::Union{Tuple, AbstractVector})::String
    assertstring(x) = x isa AbstractString || throw(ArgumentError("path component is not a string: $(repr(x))"))

    isempty(paths) && throw(ArgumentError("collection of path components must be non-empty"))
    assertstring(paths[1])
    path = paths[1]
    for i in firstindex(paths)+1:lastindex(paths)
        p = paths[i]
        assertstring(p)
        if isabspath(p)
            path = p
        elseif isempty(path) || path[end] == '/'
            path *= p
        else
            path *= "/" * p
        end
    end
    return path
end

end # os-test

joinpath(paths::AbstractString...)::String = joinpath(paths)

"""
    joinpath(parts::AbstractString...)::String
    joinpath(parts::Vector{AbstractString})::String
    joinpath(parts::Tuple{AbstractString})::String

Join path components into a full path. If some argument is an absolute path or
(on Windows) has a drive specification that doesn't match the drive computed for
the join of the preceding paths, then prior components are dropped.

Note on Windows since there is a current directory for each drive, `joinpath("c:", "foo")`
represents a path relative to the current directory on drive "c:" so this is equal to "c:foo",
not "c:\\foo". Furthermore, `joinpath` treats this as a non-absolute path and ignores the drive
letter casing, hence `joinpath("C:\\\\A","c:b") = "C:\\\\A\\\\b"`.

# Examples
```jldoctest
julia> joinpath("/home/myuser", "example.jl")
"/home/myuser/example.jl"
```

```jldoctest
julia> joinpath(["/home/myuser", "example.jl"])
"/home/myuser/example.jl"
```
"""
joinpath

function _split_at_separators(path::AbstractString; keepempty = true)
    # Equivalent to Base.split(path, r"/+"sa; keepempty) (r"[\\/]+"sa on windows)
    # Since there is no split between consecutive separators, keepempty
    # only has an effect on strings starting or ending with separators.
    out = String[]
    start = 1

    while true
        nextsep = findnext(isseparator, path, start)

        stop = isnothing(nextsep) ? lastindex(path) : prevind(path, nextsep)

        substr = String(view(path, start:stop))
        if keepempty || !isempty(substr)
            push!(out, substr)
        end

        isnothing(nextsep) && break

        start = something(findnext(!isseparator, path, nextsep+1), nextind(path, lastindex(path)))
    end
    return out
end

"""
    normpath(path::AbstractString)::String

Normalize a path, removing "." and ".." entries and changing "/" to the canonical path separator
for the system.

# Examples
```jldoctest
julia> normpath("/home/myuser/../example.jl")
"/home/example.jl"

julia> normpath("Documents/Julia") == joinpath("Documents", "Julia")
true
```
"""
function normpath(path::String)
    isabs = isabspath(path)
    isdir = isdirpath(path)
    drive, path = splitdrive(path)
    parts = _split_at_separators(path, keepempty = false)
    filter!(!=("."), parts)
    while true
        clean = true
        for j = 1:length(parts)-1
            if parts[j] != ".." && parts[j+1] == ".."
                deleteat!(parts, j:j+1)
                clean = false
                break
            end
        end
        clean && break
    end
    if isabs
        while !isempty(parts) && parts[1] == ".."
            popfirst!(parts)
        end
    elseif isempty(parts)
        push!(parts, ".")
    end
    path = join(parts, path_separator)
    if isabs
        path = path_separator*path
    end
    if isdir && !isdirpath(path)
        path *= path_separator
    end
    string(drive,path)
end

"""
    normpath(path::AbstractString, paths::AbstractString...)::String

Convert a set of paths to a normalized path by joining them together and removing
"." and ".." entries. Equivalent to `normpath(joinpath(path, paths...))`.
"""
normpath(a::AbstractString, b::AbstractString...) = normpath(joinpath(a,b...))

"""
    abspath(path::AbstractString)::String

Convert a path to an absolute path by adding the current directory if necessary.
Also normalizes the path as in [`normpath`](@ref).

# Examples

If you are in a directory called `JuliaExample` and the data you are using is two levels up relative to the `JuliaExample` directory, you could write:

    abspath("../../data")

Which gives a path like `"/home/JuliaUser/data/"`.

See also [`joinpath`](@ref), [`pwd`](@ref), [`expanduser`](@ref).
"""
@noinline function abspath(a::String)::String
    if !isabspath(a)
        cwd = pwd()
        a_drive, a_nodrive = splitdrive(a)
        if a_drive != "" && lowercase(splitdrive(cwd)[1]) != lowercase(a_drive)
            cwd = a_drive * path_separator
            a = joinpath(cwd, a_nodrive)
        else
            a = joinpath(cwd, a)
        end
    end
    return normpath(a)
end

"""
    abspath(path::AbstractString, paths::AbstractString...)::String

Convert a set of paths to an absolute path by joining them together and adding the
current directory if necessary. Equivalent to `abspath(joinpath(path, paths...))`.
"""
abspath(a::AbstractString, b::AbstractString...) = abspath(joinpath(a,b...))

if Sys.iswindows()

function longpath(path::AbstractString)
    p = cwstring(path)
    buf = zeros(UInt16, length(p))
    while true
        n = ccall((:GetLongPathNameW, "kernel32"), stdcall,
            UInt32, (Ptr{UInt16}, Ptr{UInt16}, UInt32),
            p, buf, length(buf))
        windowserror(:longpath, n == 0)
        x = n < length(buf) # is the buffer big enough?
        resize!(buf, n) # shrink if x, grow if !x
        x && return transcode(String, buf)
    end
end

end # os-test


"""
    realpath(path::AbstractString)::String

Canonicalize a path by expanding symbolic links and removing "." and ".." entries.
On case-insensitive case-preserving filesystems (typically Mac and Windows), the
filesystem's stored case for the path is returned.

(This function throws an exception if `path` does not exist in the filesystem.)
"""
function realpath(path::AbstractString)
    req = Libc.malloc(_sizeof_uv_fs)
    try
        ret = ccall(:uv_fs_realpath, Cint,
                    (Ptr{Cvoid}, Ptr{Cvoid}, Cstring, Ptr{Cvoid}),
                    C_NULL, req, path, C_NULL)
        if ret < 0
            uv_fs_req_cleanup(req)
            uv_error("realpath($(repr(path)))", ret)
        end
        path = unsafe_string(ccall(:jl_uv_fs_t_ptr, Cstring, (Ptr{Cvoid},), req))
        uv_fs_req_cleanup(req)
        return path
    finally
        Libc.free(req)
    end
end

if Sys.iswindows()

function homedir(username::AbstractString)
    # For the current user, just return homedir().
    current_user = try
        Sys.username()
    catch err
        err isa IOError || rethrow()
        nothing
    end
    if username == current_user
        return homedir()
    end
    # Look up the user's SID, then query the registry for their profile path.
    # This is the same approach Go uses (os/user.Lookup on Windows).
    home = _win_profile_from_registry(username)
    home !== nothing && return home
    # Fallback: assume profiles are siblings in the same parent directory,
    # but only if the current user's home follows the <parent>/<username>
    # convention. If not, we can't guess reliably.
    userhome = homedir()
    if current_user !== nothing && basename(userhome) == current_user
        home = joinpath(dirname(userhome), username)
        isdir(home) && return home
    end
    return nothing
end
function _win_profile_from_registry(username::AbstractString)
    # Step 1: Resolve username to a SID via LookupAccountNameW.
    # First call with zero-length buffers to get required sizes.
    wuser = cwstring(username)
    sid_size = Ref{UInt32}(0)
    domain_size = Ref{UInt32}(0)
    use = Ref{Int32}(0)
    ccall((:LookupAccountNameW, "advapi32"), stdcall, Cint,
          (Ptr{UInt16}, Ptr{UInt16}, Ptr{Cvoid}, Ptr{UInt32},
           Ptr{UInt16}, Ptr{UInt32}, Ptr{Int32}),
          C_NULL, wuser, C_NULL, sid_size, C_NULL, domain_size, use)
    sid_size[] == 0 && return nothing
    sid_buf = Vector{UInt8}(undef, sid_size[])
    domain_buf = Vector{UInt16}(undef, domain_size[])
    ret = ccall((:LookupAccountNameW, "advapi32"), stdcall, Cint,
                (Ptr{UInt16}, Ptr{UInt16}, Ptr{UInt8}, Ptr{UInt32},
                 Ptr{UInt16}, Ptr{UInt32}, Ptr{Int32}),
                C_NULL, wuser, sid_buf, sid_size, domain_buf, domain_size, use)
    ret == 0 && return nothing
    # Step 2: Convert SID to string form (e.g. "S-1-5-21-...").
    str_sid_ptr = Ref{Ptr{UInt16}}(C_NULL)
    ret = ccall((:ConvertSidToStringSidW, "advapi32"), stdcall, Cint,
                (Ptr{UInt8}, Ref{Ptr{UInt16}}), sid_buf, str_sid_ptr)
    ret == 0 && return nothing
    len = ccall(:wcslen, Csize_t, (Ptr{UInt16},), str_sid_ptr[])
    sid_str = transcode(String, unsafe_wrap(Array, str_sid_ptr[], len))
    ccall((:LocalFree, "kernel32"), stdcall, Ptr{Cvoid}, (Ptr{Cvoid},), str_sid_ptr[])
    # Step 3: Query the registry for the user's ProfileImagePath.
    subkey = cwstring("SOFTWARE\\Microsoft\\Windows NT\\CurrentVersion\\ProfileList\\$sid_str")
    value = cwstring("ProfileImagePath")
    buf_size = Ref{UInt32}(0)
    # RRF_RT_REG_SZ | RRF_RT_REG_EXPAND_SZ = 0x00000006
    HKEY_LOCAL_MACHINE = 0x80000002 % UInt
    ccall((:RegGetValueW, "advapi32"), stdcall, Clong,
          (UInt, Ptr{UInt16}, Ptr{UInt16}, UInt32, Ptr{UInt32}, Ptr{UInt16}, Ptr{UInt32}),
          HKEY_LOCAL_MACHINE, subkey, value, 0x00000006, C_NULL, C_NULL, buf_size)
    buf_size[] == 0 && return nothing
    buf = Vector{UInt16}(undef, buf_size[] ÷ 2)
    ret = ccall((:RegGetValueW, "advapi32"), stdcall, Clong,
                (UInt, Ptr{UInt16}, Ptr{UInt16}, UInt32, Ptr{UInt32}, Ptr{UInt16}, Ptr{UInt32}),
                HKEY_LOCAL_MACHINE, subkey, value, 0x00000006, C_NULL, buf, buf_size)
    ret != 0 && return nothing
    # Remove trailing null and convert to String.
    n = buf_size[] ÷ 2
    n > 0 && buf[n] == 0 && (n -= 1)
    home = transcode(String, buf[1:n])
    return isdir(home) ? home : nothing
end
function contractuser(path::Union{String, SubString{String}})::String
    # Walk prefixes of path, checking if any matches homedir() via inode.
    # Only checks the current user's home (no ~username on Windows).
    # Preserves the original path string after the matched prefix verbatim.
    home_st = stat(homedir())
    ispath(home_st) || return path
    # check the full path (home directory itself, no trailing separator)
    samefile(stat(path), home_st) && return "~"
    # scan for separators; start after the first one to skip the root
    m = findnext(path_separator_re, path, firstindex(path))
    m === nothing && return path
    while true
        m = findnext(path_separator_re, path, nextind(path, last(m)))
        m === nothing && return path
        prefix = SubString(path, 1, prevind(path, first(m)))
        st = stat(prefix)
        ispath(st) || return path
        if samefile(st, home_st)
            return "~" * SubString(path, first(m))
        end
    end
end

else # !Sys.iswindows()

function homedir(username::AbstractString)
    # Thread-safe user lookup via getpwnam_r.
    # pwd_storage holds the struct passwd; 256 bytes is a generous upper bound
    # for all supported platforms (Linux x86-64: ~56 bytes, macOS arm64: ~80 bytes).
    pwd_storage = zeros(UInt8, 256)
    # The string buffer holds the pointed-to strings (pw_name, pw_dir, etc.).
    # Start at 1024 and double on ERANGE if any string is unusually long.
    buflen = 1024
    while buflen <= 65536
        str_buf = Vector{UInt8}(undef, buflen)
        result = Ref{Ptr{Cvoid}}(C_NULL)
        ret = ccall(:getpwnam_r, Cint,
                    (Cstring, Ptr{Cvoid}, Ptr{UInt8}, Csize_t, Ptr{Ptr{Cvoid}}),
                    username, pwd_storage, str_buf, Csize_t(buflen), result)
        if ret == 34  # ERANGE: string buffer too small, retry with more space
            buflen *= 2
        elseif ret == 0 && result[] != C_NULL
            # pw_uid sits at offset 2*sizeof(Ptr) in struct passwd on all supported
            # platforms (after pw_name and pw_passwd, which are both pointer-sized)
            uid = unsafe_load(Ptr{Cuint}(pointer(pwd_storage) + 2 * sizeof(Ptr{Cvoid})))
            pd = Libc.getpwuid(uid, false)
            return pd !== nothing ? pd.homedir : nothing
        else
            return nothing  # user not found or error
        end
    end
    return nothing
end
function contractuser(path::Union{String, SubString{String}})::String
    # Walk path prefixes from shortest to longest. At each existing prefix,
    # check against the current user's home first, then the directory owner's
    # home via inode comparison. This handles symlinks transparently.
    # Preserves the original path string after the matched prefix verbatim.
    home_st = stat(homedir())
    ispath(home_st) || return path
    cache_uid = ccall(:getuid, Cuint, ())
    cache_uname = nothing
    cache_home_st = nothing
    # Check the full path (home directory itself, no trailing separator)
    samefile(stat(path), home_st) && return "~"
    # Scan for separators; start after the first one to skip the root
    m = findnext(path_separator_re, path, firstindex(path))
    m === nothing && return path
    while true
        m = findnext(path_separator_re, path, nextind(path, last(m)))
        m === nothing && return path
        prefix = SubString(path, 1, prevind(path, first(m)))
        st = stat(prefix)
        ispath(st) || return path
        rest = SubString(path, first(m))
        if samefile(st, home_st)
            return "~" * rest
        end
        uid = st.uid
        if uid != cache_uid
            cache_uid = uid
            pd = Libc.getpwuid(uid, false)
            cache_uname = pd !== nothing && !isempty(pd.username) ? pd.username : nothing
            if cache_uname !== nothing
                pw_home = homedir(cache_uname)
                cache_home_st = pw_home !== nothing ? stat(pw_home) : nothing
            else
                cache_home_st = nothing
            end
        end
        if cache_home_st !== nothing && ispath(cache_home_st) && samefile(st, cache_home_st)
            return "~$(cache_uname)" * rest
        end
    end
end

end # if Sys.iswindows()

function expanduser(path::Union{String, SubString{String}})::String
    y = iterate(path)
    y === nothing && return path
    c, i = y::Tuple{eltype(path),Int}
    c != '~' && return path
    # collect username: everything after ~ up to separator or end
    m = findnext(path_separator_re, path, i)
    j = prevind(path, m === nothing ?
        nextind(path, lastindex(path)) : first(m))
    username = SubString(path, i, j)
    # can't use a regex because of bootstrap order
    if isempty(username)
        home = homedir()
    elseif Sys.iswindows() || # ~username not supported on Windows
        !all(c -> isletter(c) || isdigit(c) || c in "._-", username) # invalid
        return path
    else
        home = homedir(username)
        home === nothing && return path
    end
    # use first separator in the rest of path in home
    if m !== nothing
        if Sys.iswindows()
            sep = path[first(m)]
            home = replace(home, path_separator_re => sep)
        end
        return home * SubString(path, first(m))
    end
    return home
end


"""
    expanduser(path::AbstractString)::AbstractString

Replace a tilde character at the start of a path with the current user's home directory.
On Unix, `~username` at the start of a path is replaced with that user's home directory;
if the user does not exist the path is returned unchanged. On Windows, only `~` expansion
is supported (not `~username`).

See also: [`contractuser`](@ref).
"""
expanduser(path::AbstractString) = expanduser(String(path))

"""
    contractuser(path::AbstractString)::AbstractString

Replace a home directory prefix in `path` with a tilde. If the path starts with the
current user's home directory it is replaced with `~`. On Unix, if it starts with
another user's home directory it is replaced with `~username`. The path is returned
unchanged if no home directory prefix is found.

See also: [`expanduser`](@ref).
"""
contractuser(path::AbstractString) = contractuser(String(path))


"""
    relpath(path::AbstractString, startpath::AbstractString = ".")::String

Return a relative filepath to `path` either from the current directory or from an optional
start directory. This is a path computation: the filesystem is not accessed to confirm the
existence or nature of `path` or `startpath`.

On Windows, case sensitivity is applied to every part of the path except drive letters. If
`path` and `startpath` refer to different drives, the absolute path of `path` is returned.
"""
function relpath(path::String, startpath::String = ".")
    isempty(path) && throw(ArgumentError("`path` must be non-empty"))
    isempty(startpath) && throw(ArgumentError("`startpath` must be non-empty"))
    curdir = "."
    pardir = ".."
    path == startpath && return curdir
    if Sys.iswindows()
        path_drive, path_without_drive = splitdrive(path)
        startpath_drive, startpath_without_drive = splitdrive(startpath)
        isempty(startpath_drive) && (startpath_drive = path_drive) # by default assume same as path drive
        uppercase(path_drive) == uppercase(startpath_drive) || return abspath(path) # if drives differ return first path
        path_arr  = _split_at_separators(abspath(path_drive * path_without_drive))
        start_arr = _split_at_separators(abspath(path_drive * startpath_without_drive))
    else
        path_arr  = _split_at_separators(abspath(path))
        start_arr = _split_at_separators(abspath(startpath))
    end
    i = 0
    while i < min(length(path_arr), length(start_arr))
        i += 1
        if path_arr[i] != start_arr[i]
            i -= 1
            break
        end
    end
    pathpart = join(path_arr[i+1:something(findlast(x -> !isempty(x), path_arr), 0)], path_separator)
    prefix_num = something(findlast(x -> !isempty(x), start_arr), 0) - i - 1
    if prefix_num >= 0
        prefix = pardir * path_separator
        relpath_ = isempty(pathpart)     ?
            (prefix^prefix_num) * pardir :
            (prefix^prefix_num) * pardir * path_separator * pathpart
    else
        relpath_ = pathpart
    end
    return isempty(relpath_) ? curdir :  relpath_
end
relpath(path::AbstractString, startpath::AbstractString) =
    relpath(String(path)::String, String(startpath)::String)

for f in (:isdirpath, :splitdir, :splitdrive, :splitext, :normpath, :abspath, :isabspath)
    @eval $f(path::AbstractString) = $f(String(path)::String)
end

function encode_uri_component(s::AbstractString)
    out = empty!(StringVector(sizeof(s)))
    for cu in utf8units(s)
        # RFC3986 Section 2.3
        if (UInt8('A') <= cu <= UInt8('Z') ||
            UInt8('a') <= cu <= UInt8('z') ||
            UInt8('0') <= cu <= UInt8('9') ||
            cu in map(UInt8, ('-', '_', '.', '~', '/'))
        )
            push!(out, cu)
        else
            # RFC3986 Section 2.1
            push!(out, UInt8('%'))
            append!(out, codeunits(uppercase(string(cu, base = 16))))
        end
    end
    String(out)
end

"""
    uripath(path::AbstractString)

Encode `path` as a URI as per [RFC8089: The "file" URI
Scheme](https://www.rfc-editor.org/rfc/rfc8089), [RFC3986: Uniform Resource
Identifier (URI): Generic Syntax](https://www.rfc-editor.org/rfc/rfc3986), and
the [Freedesktop File URI spec](https://www.freedesktop.org/wiki/Specifications/file-uri-spec/).

## Examples

```julia-repl
julia> uripath("/home/user/example file.jl") # On a unix machine
"file://<hostname>/home/user/example%20file.jl"

julia> uripath("C:\\Users\\user\\example file.jl") # On a windows machine
"file:///C:/Users/user/example%20file.jl"
```
"""
function uripath end

@static if Sys.iswindows()
    function uripath(path::String)
        path = abspath(path)
        if startswith(path, "\\\\") # UNC path, RFC8089 Appendix E.3
            unixpath = join(_split_at_separators(path, keepempty=false), '/')
            string("file://", encode_uri_component(unixpath)) # RFC8089 Section 2
        else
            drive, localpath = splitdrive(path) # Assuming that non-UNC absolute paths on Windows always have a drive component
            unixpath = join(_split_at_separators(localpath, keepempty=false), '/')
            encdrive = replace(encode_uri_component(drive), "%3A" => ':', "%7C" => '|') # RFC8089 Appendices D.2, E.2.1, and E.2.2
            string("file:///", encdrive, '/', encode_uri_component(unixpath)) # RFC8089 Section 2
        end
    end
else
    function uripath(path::String)
        localpath = join(_split_at_separators(abspath(path), keepempty=false), '/')
        host = if ispath("/proc/sys/fs/binfmt_misc/WSLInterop") # WSL sigil
            distro = get(ENV, "WSL_DISTRO_NAME", "") # See <https://patrickwu.space/wslconf/>
            "wsl\$/$distro" # See <https://github.com/microsoft/terminal/pull/14993> and <https://learn.microsoft.com/en-us/windows/wsl/filesystems>
        else
            gethostname() # Freedesktop File URI Spec, Hostnames section
        end
        string("file://", encode_uri_component(host), '/', encode_uri_component(localpath)) # RFC8089 Section 2
    end
end

uripath(path::AbstractString) = uripath(String(path)::String)