fs

Filesystem access: paths, files, directories, metadata, and permissions.

Ordinary metadata such as size, timestamps, ownership, permissions, and file attributes are available through Metadata and update_metadata. Extended attributes use xattrs and related functions. POSIX and NFSv4 ACLs use acl and set_acl. Windows security descriptors can also be fetched and manipulated with full fidelity; see fs.windows.sec_desc and the Security Guide. Windows alternate data streams are listed with streams.

Types

Type	Description
`DirEntry`	An entry within a directory.
`File`	An open file.
`FileLock`	The state of a scoped `File` lock.
`FsMetadata`	Metadata about a filesystem as a whole.
`Metadata`	Metadata about a single filesystem entry.
`Path`	A filesystem path.
`XattrEntry`	An extended attribute of a filesystem entry.
`CloneMode`	How a copy shares blocks between its source and destination.
`FileType`	The type of a file.
`OpenMode`	File access mode accepted by `open`.
`Resolve`	Resolution mode
`XattrNamespace`	An extended-attribute namespace: a name, or `:USER:` or `:SYSTEM:` for the well-known namespaces.

`CloneMode = (:AUTO: | :REQUIRE: | :NEVER:)`

How a copy shares blocks between its source and destination.

Value	Meaning
`:AUTO:`	share blocks where possible, copy the data otherwise
`:REQUIRE:`	fail rather than copy the data outright
`:NEVER:`	copy the data outright even where sharing is available

`FileType = (:FILE: | :DIR: | :SYMLINK: | :FIFO: | :CHAR_DEVICE: | :BLOCK_DEVICE: | :SOCKET: | :UNKNOWN:)`

The type of a file.

Value	Description
`:FILE:`	Regular file
`:DIR:`	Directory
`:SYMLINK:`	Symbolic link
`:FIFO:`	Named pipe (FIFO)
`:CHAR_DEVICE:`	Character device
`:BLOCK_DEVICE:`	Block device
`:SOCKET:`	Unix domain socket
`:UNKNOWN:`	Type could not be determined

`OpenMode = ("r" | "w" | "a" | "r+" | "w+" | "a+" | "rb" | "wb" | "ab" | "r+b" | "w+b" | "a+b")`

File access mode accepted by open.

Mode	Description
`"r"`	Read-only
`"w"`	Write-only (truncates existing file)
`"a"`	Append to existing file
`"r+"`	Read and write
`"w+"`	Read and write (truncates existing file)
`"a+"`	Read and append

A "b" suffix selects binary mode, as in "rb", "wb", or "r+b".

`Resolve = (:TARGET: | :LINK:)`

Resolution mode

Many functions accept a resolve: parameter that controls how symbolic links and other recursive path resolution is handled. Two values are accepted:

:TARGET: — Resolve all links to their final target. This is the default for most functions.
:LINK: — Resolve all links except the final component. For example, given a symlink link -> target, metadata link resolve: :LINK: returns the link's own metadata rather than the target's. This is the default for glob.

On Unix, :LINK: corresponds to lstat-style behavior. On Windows, it applies to both symbolic links and other reparse points such as directory junctions.

`XattrNamespace = (Str | :USER: | :SYSTEM:)`

An extended-attribute namespace: a name, or :USER: or :SYSTEM: for the well-known namespaces.

Functions

`absolute path -> Path`

Returns the absolute form of a path based on the current working directory.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to make absolute.

Example

let abs = absolute "./config.txt"
echo $abs  # /current/working/dir/config.txt

`acl path … -> (security.AnyAcl | nil)`

Gets the ACL stored on a path.

POSIX ACLs (kind: :POSIX:, the default) are supported on Linux and FreeBSD. NFSv4 ACLs (kind: :NFS4:) are supported on FreeBSD only. macOS ACLs (kind: :MACOS:) are supported on macOS only.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to query.
`:kind?`	`(:POSIX: \| :NFS4: \| :MACOS:)`	ACL format to query. Defaults to `:POSIX:`.
`:default?`	`Bool`	Query the directory's inheritable default ACL.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Returns

security.unix.Acl, security.nfs4.Acl, or security.macos.Acl, depending on kind, or nil when no ACL metadata is stored.

Errors

Exception	Condition
`ValueError`	`kind: :NFS4:` or `:MACOS:` is combined with `default: true`
`sys.UnsupportedError`	The target and ACL format combination is unsupported

`append path content -> Int`

Appends content to a file, creating it if needed.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to append to.
`content`	`(Str \| Bin)`	Content to append.

Returns

The number of bytes written.

Example

append "messages.txt" "another message\n"
append "data.bin" b"\x04\x05"

`cache_dir … -> Path`

Returns the platform-native user cache directory.

Parameters

Name	Type	Description
`:app?`	`Str`	Application name to scope the result to.

`:app`

Platform behavior

Without app, the base directories are:

Platform	Result
Non-macOS Unix	`$XDG_CACHE_HOME`, otherwise `~/.cache`
macOS	`(home_dir() / "Library" / "Caches")`
Windows	`FOLDERID_LocalAppData`, typically `(home_dir() / "AppData" / "Local")`

With app: myapp:

Platform	Result
Non-macOS Unix	`(cache_dir() / "myapp")`
macOS	`(cache_dir() / "myapp")`
Windows	`(cache_dir() / "myapp" / "Cache")`

Example

let cache = cache_dir app: blastinator8000
echo "Cache: $cache"

`canonical path -> Path`

Returns the canonical, absolute form of a path, with all intermediate components normalized and symbolic links resolved.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to canonicalize.

Example

let abs = canonical "./foo/../bar"
echo $abs  # /current/working/dir/bar (with symlinks resolved)

`copy from to …`

Copies a filesystem entry from one location to another.

By default this copies a single file or symlink. With all: true, it also copies directories recursively.

Parameters

Name	Type	Description
`from`	`(Str \| Path)`	Source path.
`to`	`(Str \| Path)`	Destination path.
`:all?`	`Bool`	Allow a recursive directory copy.

Example

copy "source.txt" "backup.txt"
copy "project" "project-backup" all: true

`copy_data src dst … -> Int`

Copies data from one open file to another.

This attempts to copy data in the most efficient manner possible:

If both handles are from the same VFS domain, all copying occurs target-side rather than being relayed.
Copy-on-write cloning of blocks/extents will be used by default if the platform, filesystem, handle pair, and data size and alignment meet relevant requirements.
Sparsity will be preserved if possible: blocks of all zero bytes which are not physically allocated in the source will not be allocated in the destination, so long as platform, filesystem, data size and alignment requirements permit it.

This operation is not remotely atomic. Concurrent modification of either source or destination in the relevant range will result in unspecified final state in terms of the destination's content in the affected range, and possibly file length if the range overlapped the prior end-of-file. A failed operation may also leave the destination in an unspecified intermediate state.

Copying between disjoint regions of one file is allowed; overlapping ones are rejected if detected. Detection requires recognizing when two handles refer to the same file, which is not always possible, in which case an overlapping copy has an unspecified result.

Parameters

Name	Type	Description
`src`	`File`	Handle to read from.
`dst`	`File`	Handle to write to.
`:range?`	`Range[Int]`	Absolute byte region of the source.
`:size?`	`Int`	Number of bytes to take from the source cursor.
`:offset?`	`Int`	Absolute byte offset in the destination.
`:clone?`	`CloneMode`	How blocks should be shared between the source and destination.

`:range`

Source Addressing

`range:`	`size:`	Source
given	—	that absolute region
—	given	that many bytes from the cursor
—	—	the cursor to the end of the file
given	given	an error — a range already carries its length

range: follows the same conventions as File.lock: half-open, .. is the whole file, an open end means "to the end of the file", an omitted start is 0, step must be 1, and endpoints counted from the end are rejected.

Using cursor-based source addressing advances the cursor by the amount copied on success.

`:offset`

Destination Addressing

offset: writes at an absolute position and leaves the destination cursor where it was; without it the copy lands at the cursor, which advances. A handle opened for appending does not support a specified offset.

As expected, if the destination position would write past the current end-of-file, the length of the file is extended.

`:clone`

Clone Behavior

On Linux and FreeBSD, :AUTO: opportunistically performs copy-on-write cloning for local filesystems and server-side copying for network mounts. :REQUIRE: explicitly requests a copy-on-write clone and fails if not possible. On Windows, :AUTO: opportunistically performs ReFS extent duplication or SMB server-side copy when possible, while :REQUIRE: only attempts the ReFS path (which may also work remotely). :REQUIRE: fails with UnsupportedError when the filesystem, file pair, or range cannot be cloned. Append destinations cannot guarantee cloning, so they also reject :REQUIRE:. macOS does not support range clones, nor do copies between different VFS domains, and thus :REQUIRE: always fails.

Sparsity

Positional copies on Linux, FreeBSD, Windows, and macOS targets preserve source holes (unallocated data blocks containing only logical zero bytes) when the filesystem exposes them, and replace existing destination data in those holes with zeroes. Hole deallocation is best effort: when it is unavailable the zeroes may consume physical storage. On Windows, a file must be explicitly marked sparse to permit unallocated zero blocks; this operation will not do so automatically.

Returns

Int, the number of bytes copied. This is the number of bytes requested unless source end-of-file was reached.

Errors

Exception	Condition
`ValueError`	`range:` and `size:` together, or a malformed range
`StateError`	`offset:` on a handle opened for appending
`StateError`	either handle is closed
`StateError`	one handle used as both sides through its cursor
`InvalidInputError`	the two regions overlap within one file

Example

open source.bin rb do |src|
  open dest.bin wb do |dst|
    # Splice a fixed region of the source onto wherever dst happens to be
    copy_data $src $dst range: (0..4096)

    # Copy the rest of src, advancing both cursors
    let count = copy_data $src $dst
    echo "copied $count bytes"

open archive.bin r+b do |file|
  # Both sides positional, so one handle can serve as both
  copy_data $file $file range: (0..64) offset: 8192

`create_dir path …`

Creates a directory.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the directory to create.
`:all?`	`Bool`	Create parent directories too.

Example

create_dir new_dir
create_dir a/b/c all: true

`create_temp_dir … -> Path`

Creates a temporary directory and returns its path.

Unlike with_temp_dir, this does not remove the directory — the caller owns its lifetime.

Parameters

Name	Type	Description
`:parent?`	`(Str \| Path)`	Parent directory. Defaults to `temp_dir()`.

Example

let dir = create_temp_dir()
try
  let file = (dir / "test.txt")
  file.open w do |f|
    f.write "Hello, World!"
finally
  remove_dir $dir all: true

`entries path -> Iter[DirEntry]`

Reads the entries in a directory.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the directory.

Example

for entry = entries /home/user/docs
  echo "$(entry.name) - $(entry.type)"

let files = [...entries "."]
echo "Found $(files.len) entries"

`exists path -> Bool`

Checks whether a file or directory exists at the given path.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to check.

Example

if exists "temp.txt"
  remove "temp.txt"

`fs_metadata path … -> FsMetadata`

Gets metadata for the filesystem containing the given path.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to resolve.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Errors

Exception	Condition
`sys.UnsupportedError`	On Linux, `resolve: :LINK:` is used

Example

let meta = fs_metadata "data.txt"
echo "Available: $(meta.available)"

`glob pattern … -> Iter[Path]`

Returns an iterator over paths matching a glob pattern.

Parameters

Name	Type	Description
`pattern`	`Str`	Glob pattern, such as `".txt"` or `"/.rs"`.
`:max_depth?`	`Int`	Maximum directory depth to traverse. Defaults to unlimited.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:LINK:`.

`pattern`

Glob pattern syntax

* — Match any sequence of characters except the path separator
? — Match a single character
** — Match any sequence of characters including path separators
[abc] — Match any character in the set
{a,b,c} — Match any of the comma-separated patterns

Example

# Find all text files
for path = glob "*.txt"
  echo "Found: $path"

# Recursive search with a depth limit
for path = glob "**/*.rs" max_depth: 3
  echo "Source: $path"

# Follow symlinks
for path = glob "**/*" resolve: :TARGET:
  echo "Entry: $path"

`hard_link src dst`

Creates a hard link at dst pointing to the existing file at src.

This uses the platform-native hard-link operation. The source must already exist, and the link must be created on the same filesystem or volume if the platform requires it.

Parameters

Name	Type	Description
`src`	`(Str \| Path)`	Existing file to link to.
`dst`	`(Str \| Path)`	Path where the hard link is created.

Example

hard_link "data.txt" "data-copy.txt"

`home_dir() -> Path`

Returns the current user's home directory.

Platform	Result
Unix	`env["HOME"]`, or the home directory from the passwd database
Windows	`FOLDERID_Profile`, typically `C:\Users\<user>`

`is_absolute path -> Bool`

Returns whether a path is absolute.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to check.

Example

if is_absolute "/etc/passwd"
  echo "Absolute path"

`metadata path … -> Metadata`

Gets metadata for the given path.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file or directory.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

let meta = metadata "data.txt"
echo "Size: $(meta.size)"

# Get symlink metadata without following
let link_meta = metadata "link.txt" resolve: :LINK:
echo "Link type: $(link_meta.type)"

`move from to …`

Moves a filesystem entry from one location to another.

This first tries a plain rename. If that fails because the source and destination are on different filesystems, it falls back to copy-and-delete. By default this moves a single file or symlink. With all: true, it also moves directories recursively.

Parameters

Name	Type	Description
`from`	`(Str \| Path)`	Source path.
`to`	`(Str \| Path)`	Destination path.
`:all?`	`Bool`	Allow a recursive directory move.

Example

move "source.txt" "dest.txt"
move "project" "archive/project" all: true

`normalize path -> Path`

Returns a normalized path with . and .. components resolved without accessing the filesystem.

Unresolvable .. components in relative paths are preserved.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to normalize.

Example

let clean = normalize "./foo/../bar/./baz"
echo $clean  # bar/baz

`open path … -> File`

Opens a file.

The file stays open until File.close is called.

let file = open data.txt w
file.write "some data"
file.close()

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to open.
`mode?`	`OpenMode`	File access mode. Defaults to `"r"`.

`open[R] path func -> R`

Opens a file for reading and runs a block with it. The file is closed when the block returns.

open config.txt do |file|
  echo "Content: $(file.read())"

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to open.
`func`	`((File) -> R)`	Block to run with the file.

`open[R] path mode func -> R`

Opens a file with a mode and runs a block with it. The file is closed when the block returns.

open log.txt a do |file|
  file.write "entry\n"

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to open.
`mode`	`OpenMode`	File access mode.
`func`	`((File) -> R)`	Block to run with the file.

`read path -> Str`

Reads the entire contents of a text file in one call.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to read.

Errors

RuntimeError if the file is not valid UTF-8.

Example

let text = read "config.txt"

`read path mode -> Bin`

Reads the entire contents of a file in one call as binary data.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to read.
`mode`	`"b"`	Binary mode.

Example

let data = read "archive.bin" "b"

`read_link path -> Path`

Reads the target of a symbolic link.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the symlink.

Returns

The path the symlink points to.

Errors

Exception	Condition
`sys.NotFoundError`	The path does not exist
`sys.PermissionDeniedError`	Permission denied to read the symlink
`sys.UnsupportedError`	Reading symlinks is not supported on this platform

Example

let link = read_link "./my_link"
echo "Link points to: $link"

`relative path … -> Path`

Returns a path relative to a base directory.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to make relative.
`base?`	`(Str \| Path)`	Base directory. Defaults to the current working directory.

Returns

The original path if it cannot be made relative.

Example

# Relative to the current directory
let rel = relative "/home/user/docs/file.txt"
echo $rel  # docs/file.txt (if cwd is /home/user)

# Relative to a specific base
let rel2 = relative "/a/b/c/d" "/a/b"
echo $rel2  # c/d

`remove *paths …`

Removes one or more paths from the filesystem.

By default this removes a single file or symlink. With all: true, it also removes directories recursively, similar to rm -r. With ignore: true, missing paths are treated as success.

Parameters

Name	Type	Description
`:all?`	`Bool`	Remove directories recursively.
`:ignore?`	`Bool`	Treat a missing path as success.
`*paths`	`(Str \| Path)`	One or more paths to remove.

Example

remove "temp.txt"
remove "missing.txt" ignore: true
remove "build" all: true
remove "a.txt" "b.txt"

`remove_dir *paths …`

Removes one or more directories.

By default this removes only empty directories. With all: true, it removes directories recursively, but only through subtrees that contain directories and no files or other non-directory entries. Use remove to delete directories that contain files.

Parameters

Name	Type	Description
`:all?`	`Bool`	Recursively prune empty directory subtrees.
`:ignore?`	`Bool`	Ignore missing directories and file-blocked subtrees.
`*paths`	`(Str \| Path)`	One or more directories to remove.

Example

# Remove an empty directory
remove_dir empty_dir

# Remove an empty directory tree
remove_dir dir_to_remove all: true

# Prune only the empty branches and ignore file-blocked subtrees
remove_dir cache tmp all: true ignore: true

`remove_xattr path name …`

Removes an extended attribute.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to update.
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`:namespace?`	`XattrNamespace`	Namespace to update.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

remove_xattr "data.txt" "comment"

`rename from to …`

Renames a file or directory.

By default this replaces an existing destination. Set replace to false to fail atomically instead.

Note

replace: false is not supported on FreeBSD.

Parameters

Name	Type	Description
`from`	`(Str \| Path)`	Source path.
`to`	`(Str \| Path)`	Destination path.
`:replace?`	`Bool`	Whether to replace an existing destination.

Example

rename "old_name.txt" "new_name.txt"
rename "file.txt" "subdir/file.txt"

# Fail if the destination exists
rename "draft.txt" "published.txt" replace: false

`set_acl path acl …`

Sets or removes an ACL.

A built ACL supplies its format; an explicit kind: must match it. An untyped iterable of declarative ACE dictionaries requires an explicit kind: and is coerced by that ACL family. With nil, kind: selects the format to remove and defaults to :POSIX:.

POSIX ACLs are supported on Linux and FreeBSD, NFSv4 ACLs on FreeBSD, and macOS ACLs on macOS. Other target and format combinations raise sys.UnsupportedError.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to update.
`acl`	`(security.AclSpec \| nil)`	ACL or declarative ACE sequence.
`:kind?`	`(:POSIX: \| :NFS4: \| :MACOS:)`	Required for an untyped ACL specification.
`:default?`	`Bool`	Update the directory's inheritable default ACL.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Errors

Exception	Condition
`ValueError`	An NFSv4/macOS ACL is combined with `default: true`
`ValueError`	A built ACL conflicts with the explicit `kind:`
`TypeError`	An untyped ACL specification is passed without `kind:`
`sys.UnsupportedError`	An NFSv4 ACL is removed with `kind: :NFS4:` and `acl: nil`; NFSv4 ACLs can be replaced but not cleared to "none"

`set_size path size`

Truncates a file to the given byte length, creating it if needed.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file.
`size`	`Int`	New file length in bytes.

Example

set_size "output.txt" 0
set_size (Path "archive.bin") 1024

`set_xattr path name value …`

Sets an extended attribute value.

On Windows, empty values are rejected. NTFS deletes the attribute instead of storing an empty value.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to update.
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`value`	`(Str \| Bin)`	Attribute bytes; strings use UTF-8.
`:namespace?`	`XattrNamespace`	Namespace to update.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

set_xattr "data.txt" "comment" "ready"
set_xattr "data.txt" "raw" b"\x00\x01"

`streams path … -> Iter[fs.windows.StreamEntry]`

Lists alternate data streams for the given path.

Windows only.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to query.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

let path = Path data.txt
for stream = streams $path
  echo "$(stream.name) $(stream.type)"
  echo (path / stream)

`symlink src dst`

Creates a symbolic link at dst pointing to src.

On Unix this creates a standard symbolic link. On Windows it determines whether the target is a file or directory by reading its metadata, and fails if the target cannot be accessed; use symlink_file or symlink_dir for explicit control.

Parameters

Name	Type	Description
`src`	`(Str \| Path)`	Target path the symlink points to.
`dst`	`(Str \| Path)`	Path where the symlink is created.

Errors

Exception	Condition
`sys.NotFoundError`	The target cannot be accessed on Windows

Example

symlink "/path/to/target" "link_name"

`symlink_dir src dst`

Creates a directory symbolic link at dst pointing to src.

On Unix this is equivalent to symlink. On Windows it creates a directory symlink, which may require appropriate permissions on some Windows versions.

Parameters

Name	Type	Description
`src`	`(Str \| Path)`	Target directory path.
`dst`	`(Str \| Path)`	Path where the symlink is created.

Example

symlink_dir "/path/to/dir" "dir_link"

`symlink_file src dst`

Creates a file symbolic link at dst pointing to src.

On Unix this is equivalent to symlink. On Windows it creates a file symlink, which may require appropriate permissions on some Windows versions.

Parameters

Name	Type	Description
`src`	`(Str \| Path)`	Target file path.
`dst`	`(Str \| Path)`	Path where the symlink is created.

Example

symlink_file "/path/to/file" "file_link"

`sync path …`

Flushes a file to durable storage, returning once the device reports it committed.

The file must already exist — unlike set_size, this does not create it.

Flushing the contents says nothing about the directory entry naming the file, which is a separate inode with its own flush. Nor is it a substitute for the guarantee on a filesystem with delayed allocation or write cancellation, where data written to a file that is removed before it is flushed may never be written at all.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file.
`:data?`	`Bool`	Flush data only, skipping unneeded metadata.

`:data`

A data-only flush (fdatasync) omits metadata a reader does not need to find the contents — notably the modification time — and so can avoid a second write to the inode. A size change is still flushed either way. Defaults to false.

Example

write scratch.bin $payload
sync scratch.bin

`temp_dir() -> Path`

Returns the platform-native directory for temporary files.

Platform	Result
Unix	`$TMPDIR`, otherwise `/tmp`
Windows	`%TMP%`, otherwise `%TEMP%`, otherwise the platform default

`update_metadata *paths …`

Updates timestamps, permissions, ownership, and filesystem attributes.

Unspecified metadata is left unchanged. Unix targets support mode, numeric or named owner and group values, and applicable filesystem attributes. Windows targets accept an account name or Sid for owner and group and support applicable filesystem attributes. Unix supports modified and accessed timestamps; Windows also supports created.

Paths are submitted from left to right and processing stops at the first error. Within each path, ownership, mode, attributes, and timestamps are applied in that order. Backends may use multiple system operations; atomicity and rollback behavior are unspecified.

Clearing sparse on Windows may allocate storage for every hole. It can be expensive, may fail when the volume lacks space, and is not transactional.

Parameters

Name	Type	Description
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.
`:mode?`	`(Int \| fs.unix.Mode)`	Unix permission mode.
`:owner?`	`(Int \| Str \| security.windows.Sid)`	Owner ID, name, or SID.
`:group?`	`(Int \| Str \| security.windows.Sid)`	Group ID, name, or SID.
`:modified?`	`time.DateTime`	New modification time.
`:accessed?`	`time.DateTime`	New access time.
`:created?`	`time.DateTime`	New creation time. Windows only.
`:readonly?`	`Bool`	Readonly attribute. Windows.
`:hidden?`	`Bool`	Hidden attribute or flag.
`:system?`	`Bool`	System attribute. Windows.
`:archive?`	`Bool`	Archive attribute. Windows.
`:compressed?`	`Bool`	Compressed flag.
`:sparse?`	`Bool`	Sparse attribute. Windows.
`:temporary?`	`Bool`	Temporary attribute. Windows.
`:offline?`	`Bool`	Offline attribute. Windows.
`:not_content_indexed?`	`Bool`	Not-content-indexed attribute. Windows.
`:immutable?`	`Bool`	Immutable flag.
`:append_only?`	`Bool`	Append-only flag.
`:no_dump?`	`Bool`	No-dump flag.
`:no_atime?`	`Bool`	No-atime flag. Linux.
`:no_copy_on_write?`	`Bool`	No-copy-on-write flag. Linux.
`:dir_sync?`	`Bool`	Synchronous-directory-updates flag. Linux.
`:casefold?`	`Bool`	Casefold flag. Linux.
`:data_journaling?`	`Bool`	Data-journaling flag. Linux.
`:no_compress?`	`Bool`	Don't-compress flag. Linux.
`:project_inherit?`	`Bool`	Project-hierarchy flag. Linux.
`:secure_delete?`	`Bool`	Secure-deletion flag. Linux.
`:sync?`	`Bool`	Synchronous-updates flag. Linux.
`:no_tail_merge?`	`Bool`	No-tail-merging flag. Linux.
`:top_dir?`	`Bool`	Top-of-directory-hierarchy flag. Linux.
`:undelete?`	`Bool`	Undeletable flag. Linux.
`:direct_access?`	`Bool`	Direct-access flag. Linux.
`:extent_format?`	`Bool`	Extent-format flag. Linux.
`:opaque?`	`Bool`	Opaque flag. macOS.
`*paths`	`(Str \| Path)`	Paths to update, in order.

Errors

Exception	Condition
`sys.UnsupportedError`	The operation is used on an unsupported platform

Example

update_metadata "script.sh" mode: 0o755 owner: "deploy" group: "deploy"
update_metadata "one.txt" "two.txt" mode: 0o640
update_metadata "data.txt" hidden: true
update_metadata "link" group: "www-data" resolve: :LINK:
update_metadata "artifact.tar" modified: $DateTime.from_unix(1700000000)

`with_temp_dir[R] func … -> R`

Creates a temporary directory, invokes a function with the directory path, then removes the directory recursively upon return or error.

Parameters

Name	Type	Description
`func`	`((Path) -> R)`	Called with a `Path` to the temporary directory.
`:parent?`	`(Str \| Path)`	Parent directory. Defaults to `temp_dir()`.

Example

# Use the temporary directory in the default location
with_temp_dir do |dir|
  let file = (dir / "test.txt")
  file.open w do |f|
    f.write "Hello, World!"
  echo "Wrote to: $file"

# Use a custom parent directory
with_temp_dir parent: my_temp do |dir|
  echo $dir

`write path content -> Int`

Writes the entire contents of a file in one call, creating or truncating it.

Binary values are written as raw bytes and strings as UTF-8 text.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to the file to write.
`content`	`(Str \| Bin)`	Value to write.

Returns

The number of bytes written.

Example

write "message.txt" "hello"
write "data.bin" b"\x01\x02\x03"

`xattr path name … -> Bin`

Gets an extended attribute value.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to query.
`name`	`(Str \| XattrEntry)`	Attribute name or entry from `xattrs`.
`:namespace?`	`XattrNamespace`	Namespace to query.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

let value = xattr "data.txt" "comment"

`xattrs path … -> Iter[XattrEntry]`

Lists extended attributes for the given path.

On Windows, this uses NTFS extended attributes. Returned names may differ in case from the requested name.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path to query.
`:namespace?`	`(XattrNamespace \| :ANY:)`	Namespace to query; `:ANY:` lists all namespaces.
`:resolve?`	`Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

for attr = xattrs "data.txt"
  echo $attr.name