---
slug: 30-io-files
title: Files & I/O
description: Read, write, search and navigate the filesystem in Synsema — atomic writes, line ranges, list_dir, grep — all gated by the file capability.
example_ids: [io]
---

# Files & I/O

All file access is gated by the `file` capability (`file.read` / `file.write` for least-privilege). Writes are **atomic** (temp file + rename).

```synsema
-- Doc example: files & I/O. Needs file capability (deny-by-default).
intent: "doc example: files and I/O"
require file("_doctest_io.txt")

write_file("_doctest_io.txt", "hi from the io demo")
print("read back → " + read_file("_doctest_io.txt"))

test "write then read round-trips (atomic write)"
    write_file("_doctest_io.txt", "hello\nworld")
    assert_eq(read_file("_doctest_io.txt"), "hello\nworld")
    assert(file_exists("_doctest_io.txt"))
```

## Reading

```synsema
read_file(path)                 -- whole file as text
read_file(path, 1, 100)         -- a line range: lines 1–100 (1-based, EOLs preserved)
read_file(path, 500)            -- from line 500 to EOF
read_file_bytes(path)           -- byte-exact, for binary
```

## Writing & editing

```synsema
write_file(path, text)          -- atomic overwrite
append_file(path, text)         -- append
edit_file(path, old, new)       -- exact-string replace (old must be unique; replace_all? for all)
```

## Navigating & searching

```synsema
file_exists(path)               -- bool
file_info(path)                 -- {name, is_dir, size, ...}
list_dir(path)                  -- list of {name, is_dir, size}
grep(target, pattern, opts?)    -- {matches: [{file, line, col, text}], truncated} — streams per line
```

Path scopes are faithful — a `..` escape outside the declared scope is denied. See **[Capabilities](/en/0.6.x/20-capabilities)**.