Anchored filesystem operations

Import (sigil fs anchored) when another process may change the directory tree you are updating. Its directory handles own descriptors opened with O_DIRECTORY | O_NOFOLLOW | O_CLOEXEC. An opened handle continues to address the same directory inode when its pathname is renamed or replaced.

The first implementation supports Linux with glibc or musl. Android and other platforms raise io-error with unsupported on this platform; there is no pathname fallback. A kernel or filesystem lacking renameat2(RENAME_NOREPLACE) also raises an explicit error. macOS support using openat and renameatx_np(RENAME_EXCL) is planned.

Handles and names

(open-directory path) walks an absolute or relative path one directory at a time, refusing symlinks at every component. /, ., repeated slashes and dot components are accepted. Dot-dot components and embedded NUL bytes are refused. Relative paths start from the working directory at the time of the call.

Every relative operation takes a handle and a single basename: a nonempty string with no slash or NUL, excluding . and ... Open intermediate directories explicitly with open-directory-at; never pass parent/leaf to an operation. Symlink targets are opaque strings, so their slashes and dot-dot are permitted. Targets still cannot contain NUL.

ProcedureResult and behavior
(directory-handle? value)Boolean, including closed handles
(open-directory path)New owned handle; no component follows a symlink
(open-directory-at parent name)New owned child handle; refuses a symlink
(directory-handle-fd handle)Borrowed integer descriptor
(directory-handle-stat handle)fstat metadata for the opened directory
(close-directory handle)Close once; repeated cleanup is harmless
(call-with-directory path proc)Call proc with the handle, close on scope exit

Keep a handle reachable and open while borrowing its descriptor. Never close, duplicate over, or repurpose the borrowed descriptor. A finalizer closes unreachable handles, but collection is not prompt cleanup. Use scoped cleanup or dynamic-wind for child handles. O_CLOEXEC closes descriptors across exec; fork alone inherits them, as usual for POSIX descriptors.

Files and entries

ProcedureResult and behavior
(open-input-file-at handle name)Text input port; refuses symlinks and nonregular files
(open-output-file-at handle name [mode])Text output port; exclusive create, default #o600
(make-directory-at handle name [mode])Create a directory, default #o755
(make-symlink-at target handle name)Create a symlink; refuse an existing entry
(read-symlink-at handle name)Target string; refuse non-links
(file-stat-at handle name)Metadata without following the leaf, #f only for ENOENT
(delete-file-at handle name)Unlink a file or symlink entry; refuse directories
(delete-directory-at handle name)Remove an empty directory; refuse symlinks
(rename-file-at source old destination new)Atomic replacing rename between handles
(rename-file-no-replace-at source old destination new)Atomic rename refusing any existing destination
(exchange-entries-at source old destination new)Atomic exchange of two existing entries using renameat2
(sync-directory handle)fsync the opened directory descriptor
(sync-file output-port) from (sigil fs)Flush buffered output and fsync the regular file

Mutators return an unspecified value. Optional modes are positional integers from 0 through #o7777 and are reduced by the process umask. Output creation always uses O_CREAT | O_EXCL | O_NOFOLLOW | O_CLOEXEC; it never truncates an existing entry. Close the resulting ports with close-input-port or close-output-port. Nonblocking input open allows FIFO refusal without waiting for a writer.

Metadata uses the (sigil fs) stat-list shape. Its stat-dev, stat-ino, stat-type and other accessors work on both file-stat-at and directory-handle-stat. Integer fields retain their full width, using exact bignums when necessary. Comparing the handle's device and inode with a parent's fresh file-stat-at helps detect replacement of the directory entry.

Wrong argument types raise type-error. Invalid names, invalid modes, closed handles and OS failures raise io-error. OS errors identify the operation and include the error text and errno. file-stat-at returns #f only for absence; permission errors and other failures propagate. Unsupported no-replace rename never falls back to an overwriting rename.

Mount-safe opens and pinned metadata

open-entry-at, open-directory-no-crossing-at and create-file-at require Linux openat2. Their resolve flags refuse mount crossings, including bind mounts, and prevent lookup from following symlinks or magic links. A pinned entry can be a symlink itself. The starting directory handle determines the mount boundary. Existing open-directory and open-directory-at can cross mounts while acquiring that starting handle.

An unavailable openat2 raises io-error with openat2 unsupported. Mount crossings raise io-error with EXDEV. There is no fallback lookup. Use call-with-entry-at for deterministic cleanup. A finalizer closes entries that become unreachable, and close-entry is safe to repeat.

ProcedureResult and behavior
(open-entry-at parent name)Owned O_PATH handle for a basename, including a leaf symlink
(entry-handle? value)Boolean, including closed entry handles
(call-with-entry-at parent name proc)Pin an entry for the duration of proc
(close-entry entry)Release an entry or opened regular file
(open-directory-no-crossing-at parent name)Readable directory handle. Refuses mount crossings and symlinks
(open-entry-directory entry)Open a readable handle on the already-pinned directory
(open-entry-input entry)Open an already-pinned regular file for reading through Linux procfs
(create-file-at parent name)Exclusive regular-file creation with read/write access, mode #o600 before umask
(make-staging-directory-at parent)Create a new private operation directory and return (name . handle)
(descriptor-stat handle)Stat list for the pinned inode
(descriptor-times handle)List of atime seconds and nanoseconds, then mtime seconds and nanoseconds
(read-entry-symlink entry)Target string from the pinned symlink, even after renaming
(set-descriptor-mode! handle mode)Change permission and special mode bits. Symlinks refuse this operation
(set-descriptor-owner! handle uid gid [ignore-eperm?])Set ownership, including a symlink's. Use -1 to keep either ID. An optional true flag returns #f on EPERM
(set-descriptor-times! handle asec ansec msec mnsec)Set atime and mtime through the descriptor. Nanoseconds range from 0 to 999999999
(ensure-directory-access! handle access)Repair effective read (4), write (2), or search (1) access by adding the corresponding owner bits. Returns the previous mode if changed
(directory-entries handle)Unordered (name . inode) pairs from a pinned directory
(descriptor-xattr-names handle)Extended attribute names, or an empty list on a filesystem without xattrs
(descriptor-xattr handle name)Attribute bytevector, or #f if absent
(set-descriptor-xattr! handle name bytes)Create or replace an attribute
(remove-descriptor-xattr! handle name)Remove an attribute if present
(descriptor-read! file buffer start end offset)Positioned read into a bytevector slice. Returns the number of bytes read
(descriptor-write! file buffer start end offset)Positioned write from a bytevector slice. Returns the number of bytes written
(sync-descriptor handle)Synchronize an opened readable directory or regular file

Use system.posix_acl_access and system.posix_acl_default for POSIX ACLs. For an O_PATH handle, xattr operations can use Linux 6.13's descriptor-relative xattr syscalls. They and regular-file input reopen authenticate a pinned procfs directory with a live descriptor from this process, then use that directory for the kernel-managed numeric entry. Failure to authenticate it raises io-error. Mode changes on O_PATH require fchmodat2 with AT_EMPTY_PATH. The kernel checks ownership, xattr namespace and filesystem support. Positioned I/O uses an exclusive end index and an exact integer byte offset. Short counts are possible, and zero for a nonempty read means EOF.

This example updates the symlink itself. Stat, readlink and timestamps each use the pinned descriptor, so replacing the basename between calls cannot redirect the update. Pinned timestamps require Linux AT_EMPTY_PATH support in utimensat.

(import (sigil fs anchored))

(call-with-directory "/var/lib/example"
  (lambda (directory)
    (call-with-entry-at directory "current"
      (lambda (link)
        (let ((target (read-entry-symlink link)))
          (set-descriptor-times! link 1700000000 42 1700000000 42)
          target)))))

Tree operations

Import (sigil fs tree) with (sigil fs anchored). Both walkers accept directory handles and basenames, pin each child with openat2, and reject mount crossings. A symlink is handled as a leaf.

  • (remove-tree-at parent name staging) removes a tree or a single entry. Each entry moves into protected staging, where the walker verifies the inode before deleting it. A captured replacement is restored with a no-replace rename. If another entry occupies its original name, the captured entry stays in staging with a recovery location in the error. The walker repairs owner permissions only when needed for capture, enumeration, or deletion. Repair on a pinned directory requires Linux 6.6 fchmodat2(AT_EMPTY_PATH). If unavailable, the walker raises io-error. On failure it restores repaired modes on directories that survived.
  • (copy-tree-at source-parent source-name destination-parent destination-name staging) builds the copy under staging and publishes it with a no-replace rename. It copies regular file contents, directory and file modes, binary xattrs and POSIX ACLs. It retains nanosecond access and modification times, including on symlinks, and preserves ownership when permitted. It refuses other entry types and copies each regular file independently. Source directories require read and search access. If Linux requires owner write permission to publish a read-only directory, the walker adds that bit for the rename and restores the mode through the descriptor acquired in staging. Repair on an O_PATH handle requires Linux 6.6 fchmodat2(AT_EMPTY_PATH). Copying a symlink can require the Linux 6.13 xattr syscalls even when its attribute list is empty. If a required syscall is unavailable, the copy raises io-error before publication.
  • (copy-descriptor-metadata! source destination) applies the same metadata to an existing matching descriptor. Pinned symlinks support xattrs, ownership and timestamps.

staging must be a distinct directory owned by the effective user, with mode #o700. It belongs on the removal mount or the copy destination mount. Give this directory exclusively to the operation's trusted principals. Processes sharing its owner's credentials can access it even at mode #o700, so isolate them or serialize their access. Keep staging outside a source tree. Each call creates an operation directory under it. A public racing writer can change the tree outside staging. A failed removal can leave some entries removed, and a failed cleanup can retain work under the reported staging name.

Publication and durability

This example exclusively creates a staging file, syncs its bytes, publishes it without replacing an existing destination, then syncs the directory:

(import (sigil fs anchored) (sigil io) (only (sigil fs) sync-file))

(call-with-directory "/var/lib/example"
  (lambda (directory)
    (let ((output (open-output-file-at directory "next-unique" #o600)))
      (dynamic-wind
        (lambda () #f)
        (lambda ()
          (write-string "new contents\n" output)
          (sync-file output))
        (lambda () (close-output-port output))))
    (rename-file-no-replace-at directory "next-unique" directory "published")
    (sync-directory directory)))

Choose a private, unique staging name. A refused publication leaves the staging entry available for explicit cleanup or recovery. For a rename between different directories, sync both parent handles before recording durable completion. sync-directory follows the descriptor, even if the original pathname changed. As with fsync generally, filesystems can refuse synchronization and their errors must be handled.

Both (sigil fs) and (sigil fs anchored) export sync-directory, with path and handle arguments respectively. When using both, import (except (sigil fs) sync-directory) or use an import prefix. Direct scripts already receive (sigil fs) through the prelude; use a prefix as shown in the shell cookbook.

Concurrency boundary

Handles prevent redirection through a substituted parent symlink. No-replace rename prevents overwriting a destination created after preflight. These are separate guarantees, and neither provides a transaction over a whole tree.

An opened directory may be moved outside the original tree by another process; the handle still addresses that inode. This API does not guarantee that an inode remains underneath a root directory. Hard links are not forbidden. A replacing rename or unlink acts on the current leaf entry: it does not compare that entry with a previously inspected inode. Source entries can also change before rename. Programs must supply ownership policy and appropriate writer serialization for those cases. Device/inode comparisons detect a substitution at the instant of the comparison and cannot make a later operation into compare-and-swap.