Add a new Pager type that wraps output to an external pager program when
stdout is a TTY, following the same conventions as git. The pager
command is resolved from $PAGER, falling back to `less`. An empty $PAGER
disables paging. If the pager fails to spawn, we fall back to stdout.
Previously, +explain-config wrote directly to stdout with no paging,
which meant long help text would scroll by. Now output is automatically
piped through the user's preferred pager when running interactively. A
--no-pager flag is available to disable this.
Fixes#11957
erasePage now updates page_serial_min when the first page is erased,
and asserts that only front or back pages are erased since
page_serial_min cannot represent serial gaps from middle erasure.
To enforce this invariant at the API level, PageList.eraseRows is
now private. Two public wrappers replace it: eraseHistory always
starts from the beginning of history, and eraseActive takes a y
coordinate (with bounds assertion) and always starts from the top
of the active area. This makes middle-page erasure impossible by
construction.
If a `VERSION` file is present from our build root, prefer that as our
version source of truth over `build.zig.zon`. This file is automatically
created in source tarballs and will allow us to cut pre-release tarballs
of libghostty in particular (but affects all) that has a more specific
version than what can be in build.zig.zon.
This also adds the APIs necessary to extract this via the C API.
I started prepping for a separate libghostty version but not sure if
I'll wire that up in this PR yet or not...
Until gtk 4.20.1 trackpads have kinetic scrolling behavior regardless of
`Gtk.ScrolledWindow.kinetic_scrolling`. As a workaround, set
EventControllerScroll.kinetic to false on all controllers.
`observeControllers()` has this warning:
> Calling this function will enable extra internal bookkeeping to track
controllers and emit signals on the returned listmodel. It may slow down
operations a lot.
> Applications should try hard to avoid calling this function because of
the slowdowns.
but judging from the
[source](5301a91f1c/gtk/gtkwidget.c (L12375-L12383))
this is a one time penalty since we free the result immediately
afterwards.
Fixes https://github.com/ghostty-org/ghostty/discussions/11460.
### AI usage
Zed + Opus 4.5 generated the first pass, but it missed freeing the
result of `observeControllers()` and conveniently binding
`scrolled_window` to the blueprint. Figuring out what was going on also
took a lot of [human
debugging](https://github.com/ghostty-org/ghostty/discussions/11460#discussioncomment-16245664).
Until gtk 4.20.1 trackpads have kinetic scrolling behavior regardless
of `Gtk.ScrolledWindow.kinetic_scrolling`. As a workaround, set
EventControllerScroll.kinetic to false on all controllers.
`observeControllers()` has this warning:
> Calling this function will enable extra internal bookkeeping to track controllers and emit signals on the returned listmodel. It may slow down operations a lot.
> Applications should try hard to avoid calling this function because of the slowdowns.
but judging from the [source](5301a91f1c/gtk/gtkwidget.c (L12375-L12383))
this is a one time penalty since we free the result immediately afterwards.
Fixes https://github.com/ghostty-org/ghostty/discussions/11460
The argument iterator's .next() method returns a transient slice of the
command line buffer so we need to make our own copies of these values to
avoid referencing stale memory.
Add version (std.SemanticVersion) to the terminal build options so that
the terminal module has access to the application version at comptime.
The add() function breaks it out into version_string, version_major,
version_minor, version_patch, and version_build terminal options.
On the C API side, five new GhosttyBuildInfo variants expose these
through ghostty_build_info(). String values use GhosttyString; numeric
values use size_t. When no build metadata is present, version_build
returns a zero-length string.
The c-vt-build-info example is updated to query and print all version
fields.
The argument iterator's .next() method returns a transient slice of the
command line buffer so we need to make our own copies of these values to
avoid referencing stale memory.
If `$EDITOR` or `$VISUAL` contained arguments, not just the path to an
editor (e.g. `zed --new`) `+edit-config` would fail because we were
treating the whole command as a path. Instead, wrap the command with
`/bin/sh -c <command>` so that the shell can separate the path from the
arguments.
Fixes#11897
Replace hardcoded locale.h constants and extern function declarations
with build-system TranslateC, following the same pattern as pty.c.
This fixes LC_ALL being hardcoded to 6 (the musl/glibc implementation
value), which is implementation-defined and differs on Windows MSVC
(where LC_ALL is 0), causing `setlocale()` to crash with an invalid
parameter error.
## Changes
- Added `src/os/locale.c` — includes `locale.h` for TranslateC
- Added TranslateC step in `src/build/SharedDeps.zig` (same pattern as
pty.c)
- Replaced hardcoded constants and extern declarations in
`src/os/locale.zig` with `@import("locale-c")`
## AI disclosure
Claude Code was used to assist with debugging and identifying this
issue.
Replace hardcoded locale.h constants and extern function declarations
with build-system TranslateC, following the same pattern as pty.c.
This fixes LC_ALL being hardcoded to 6 (musl/glibc value), which is
implementation-defined and differs on Windows MSVC (where LC_ALL is 0),
causing setlocale() to crash with an invalid parameter error.
If `$EDITOR` or `$VISUAL` contained arguments, not just the path to
an editor (e.g. `zed --new`) `+edit-config` would fail because we were
treating the whole command as a path. Instead, wrap the command with
`/bin/sh -c <command>` so that the shell can separate the path from
the arguments.
Fixes#11897
## Summary
This PR effectively enables testing for all the Windows related stuff
that is coming soon.
> [!IMPORTANT]
>This PR builds on top of #11782 which fixes the last (as we speak) bug
that we have in the Windows pipeline. So it would be great to review
that PR first and then work on this one. Then we'll have the real
windows testing, basically achieving parity, infrastructurally, with the
other platforms.
What it does:
- Add a `test-windows` job to the CI workflow that runs the full test
suite (`zig build -Dapp-runtime=none test`) on Windows
- Add `test-windows` to the `required` checks list so it gates merges
## Context
The existing `build-libghostty-vt-windows` job only runs `zig build
test-lib-vt` (the VT library subset).
I realized that in c5092b09d we removed the TODO comment in that job:
"Work towards passing the full test suite on Windows."
But effectively we weren't running tests in CI yet!
The full test suite now passes on Windows (51/51 steps, 2654 tests, 23
skipped). This job mirrors what the other platforms do — Linux runs `zig
build -Dapp-runtime=none test` via Nix, macOS runs `zig build test` via
Nix. Windows runs the same command directly via `setup-zig` since
there's no Nix on Windows.
## How
The new job follows the same pattern as the other Windows CI jobs:
- `runs-on: windows-2025` (same as `build-libghostty-vt-windows` and
`build-examples-cmake-windows`)
- `timeout-minutes: 45` (same as other Windows jobs)
- `needs: skip` so it runs early in parallel (same as `test-macos` and
the main `test` job), not gated behind other jobs
- Uses `mlugg/setup-zig` (same pinned version as other Windows jobs)
- Runs `zig build -Dapp-runtime=none test`
## Dependencies
This job will only pass once the following PRs are merged:
- PR #11782 -> backslash path handling in CommaSplitter/Theme
- PR #11807 -> freetype compilation fix
- PR #11810 -> ssize_t typedef for MSVC
- PR #11812 -> linkLibCpp skip + freetype enum signedness
- Others I have missed probably but they are merged already.
## Test plan
- The workflow YAML is valid (standard GitHub Actions syntax, matches
existing job patterns)
- I will be ready to issue fix PRs if any issue related to this arises.
I cannot reliably test GH actions locally unfortunately.
- Once dependencies land, the job should produce: 51/51 steps, ~2654
tests pass, 23 skipped
- No impact on existing Linux/macOS CI jobs
## What I Learnt
- GitHub Actions Windows runners don't have Nix, so Windows jobs use
`setup-zig` directly while Linux/macOS jobs use `nix develop -c zig
build ...`. The Nix wrapper ensures the exact same environment as the
flake, but on Windows we get that consistency from the `setup-zig`
action which reads the version from `build.zig.zon`.
- The `needs: skip` pattern allows a job to run in parallel with the
main test job rather than waiting for it. The main `test` job is the
gatekeeper for most build jobs (`needs: test`), but platform-specific
test jobs like `test-macos` run in parallel since they're independent.
- The `required` job aggregates all needed jobs and uses a grep-based
check to determine overall pass/fail, so adding a new job there means it
becomes a merge blocker.
Trim trailing \r when splitting octants.txt by \n at comptime. On
Windows, git may convert LF to CRLF on checkout, leaving \r at the
end of each line. Without trimming, the parser tries to use \r as
a struct field name in @field(), causing a compile error.
Follows the same pattern used in x11_color.zig for rgb.txt parsing.
Use b.allocator instead of b.graph.arena for SDK detection and
path formatting -- b.allocator is the public API, b.graph.arena
is an internal field.
Move test_dll_init.c from windows/Ghostty.Tests/ to test/windows/
with a README. Test infrastructure belongs under test/, not the
Windows app directory.
The C# test suite and ghostty_crt_workaround_active() probe were
unnecessary overhead. The DllMain workaround is harmless to keep
(CRT init is ref-counted) and comments document when to remove it.
test_dll_init.c remains as a standalone C reproducer.
C# test suite and C reproducer validating DLL initialization.
The probe test (DllMainWorkaround_IsStillActive) checks that the CRT
workaround is compiled in via ghostty_crt_workaround_active(). When
Zig fixes MSVC DLL CRT init, removing the DllMain will make this test
fail with instructions on how to verify the fix and clean up.
ghostty_init is tested via the C reproducer (test_dll_init.c) rather
than C# because the global state teardown crashes the test host on
DLL unload. The C reproducer exits without FreeLibrary.
Zig's _DllMainCRTStartup does not initialize the MSVC C runtime when
building a shared library targeting MSVC ABI. This means any C library
function that depends on CRT internal state (setlocale, glslang,
oniguruma) crashes with null pointer dereferences because the heap,
locale, and C++ runtime are never set up.
Declare a DllMain that calls __vcrt_initialize and __acrt_initialize
on DLL_PROCESS_ATTACH. Zig's start.zig checks @hasDecl(root, "DllMain")
and calls it during _DllMainCRTStartup. Uses @extern to get function
pointers without pulling in CRT objects that would conflict with Zig's
own _DllMainCRTStartup symbol.
Only compiles on Windows MSVC (comptime guard). On other platforms and
ABIs, DllMain is void and has no effect.
linkLibC() provides msvcrt.lib for DLL targets but doesn't include the
companion CRT bootstrap libraries. The DLL startup code in msvcrt.lib
calls __vcrt_initialize and __acrt_initialize, which live in the static
CRT libraries (libvcruntime.lib, libucrt.lib).
Detect the Windows 10 SDK installation via std.zig.WindowsSdk to add
the UCRT library path, which Zig's default search paths don't include
(they add um\x64 but not ucrt\x64).
This is a workaround for a Zig gap (partially addressed in closed
issues 5748, 5842 on ziglang/zig). Only affects initShared (DLL),
not initStatic.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
Trim trailing \r when splitting octants.txt by \n at comptime. On
Windows, git may convert LF to CRLF on checkout, leaving \r at the
end of each line. Without trimming, the parser tries to use \r as
a struct field name in @field(), causing a compile error.
Follows the same pattern used in x11_color.zig for rgb.txt parsing.
Trailing state capture now is encapsulated in a struct `Capture` and all
parsers access the data via `p.capture.trailing()` rather than directly
from the writer.
This is primarily to prep for the OSC parser to be able to capture the
entire sequence (not just the trailing part) so we can setup libghostty
for fallback handlers so libghostty implementers can have custom OSC
behaviors.
But, it has the benefit of making our OSC parser much cleaner too.
Add ghostty_paste_encode() which encodes paste data for writing to
the terminal pty. It strips unsafe control bytes, wraps in bracketed
paste sequences when requested, and replaces newlines with carriage
returns for unbracketed mode. The input buffer is modified in place
and the encoded result is written to a caller-provided output buffer,
following the same buffer/out_written pattern as the other encode
functions like ghostty_size_report_encode.
Update the c-vt-paste example with an encode_example() demonstrating
the new function and add corresponding @snippet references in the
header documentation.
Add set/get support for foreground, background, cursor, and palette
default colors through ghostty_terminal_set and ghostty_terminal_get.
Four new set options (COLOR_FOREGROUND, COLOR_BACKGROUND, COLOR_CURSOR,
COLOR_PALETTE) write directly to the terminal color defaults. Passing
NULL clears the value for RGB colors or resets the palette to the
built-in default. All set operations mark the palette dirty flag for
the renderer.
Eight new get data types retrieve either the effective color (override
or default, via DynamicRGB.get) or the default color only (ignoring
any OSC overrides). Effective getters for RGB colors return the new
NO_VALUE result code when no color is configured. The palette getters
return the current or original palette respectively.
Adds the GHOSTTY_NO_VALUE result code for cases where a queried value
is simply not configured, distinct from GHOSTTY_INVALID_VALUE which
indicates a caller error.
Run cmake configure and build on the extracted lib-vt tarball as
part of distcheck to ensure the CMake wrapper works from the
stripped archive. Keep dist/cmake/ and dist/libghostty-vt/ in the
archive since the CMake build needs them.
When emit_lib_vt is set, the dist tarball is now named
ghostty-vt-<version>.tar.gz and excludes large files that are
unnecessary for building libghostty-vt. This reduces the archive
from ~36MB to ~2.8MB by excluding images, macOS app resources,
font assets, fuzz test corpus, crash testdata, and vendored
libraries not used by lib-vt.
GTK resources and frame data generation are also skipped since
lib-vt does not need them, which removes the GTK build-time
dependency. The distcheck step runs test-lib-vt instead of the
full test suite for lib-vt archives.
On Windows, install as ghostty.dll + ghostty-static.lib instead of
libghostty.so + libghostty.a, following Windows naming conventions.
Guard ubsan_rt bundling in initStatic for MSVC compatibility.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
# What
CommaSplitter treats backslash as an escape character, which breaks
Windows paths like
C:\Users\foo since \U is not a valid escape. On Windows, treat backslash
as a literal character
outside of quoted strings. Inside quotes, escape sequences still work as
before.
Also fix Theme.parseCLI to not mistake the colon in a Windows drive
letter (C:\...) for a
light/dark theme pair separator.
# How
The platform behavior is controlled by a single comptime constant at the
top of CommaSplitter:
const escape_outside_quotes = builtin.os.tag != .windows;
The next() function checks this constant to decide whether backslash
triggers escape parsing
outside quoted strings. All behavior lives in one place.
For Theme, skip colon detection at index 1 on Windows so drive letters
are not mistaken for pair
separators.
Escape-specific tests are skipped on Windows with SkipZigTest.
Windows-specific tests are added
separately to cover paths, literal backslash, and
escapes-still-work-inside-quotes.
# Note
There are other places in config parsing that use colon as a delimiter
without accounting for
Windows drive letters (command.zig prefix parsing, keybind parsing).
Those are separate from this
PR.
# Verified
- zig build test-lib-vt passes on Windows (exit 0)
- No impact on Linux/macOS (the constant is true there, all existing
behavior unchanged)
# What I Learnt
- Platform behavior should live in a single constant or struct, not
scattered across if-else
branches in every test. The escape_outside_quotes constant mirrors the
pattern upstream uses with
PageAlloc = switch(builtin.os.tag) but for a simpler boolean case.
- Use error.SkipZigTest for tests that cannot run on a platform, never
silent returns. This way
the test runner reports them as skipped, not silently passed.
- When fixing a pattern (colon as delimiter), grep the whole codebase
for similar issues even if
you are not fixing them all in one PR. Note them for future work.
This parameterizes all our calling conventions on our C API based on
whether we're building the C lib or Zig lib. If we're building the C
lib, it's C calling convention, else Zig. This lets the Zig module call
the C API via `terminal.c_api.<func>`.
Zig is perfectly capable of calling C ABI but we actually modify our
struct layouts depending on calling conv so you can't actually use the
API prior to this. This fixes that all up.
**Why would you want to do this?** The C API has some different
semantics and stricter care about things like ABI compatibility (in how
it changes structs and so on). It actually might be a more API-stable
API to rely on even from Zig.
When PS1 ends with a bare '%' (e.g. `%3~ %`), concatenating our 133;B
mark (`%{...%}`) directly after it causes zsh's prompt expansion to
interpret the '%' + '{' result as a '%{' escape sequence. This swallows
the 133;B mark and produces a visible '{' in the prompt.
Work around this by doubling a trailing '%' into '%%' before appending
marks, so it expands to a literal '%' and won't merge with the `%{`
token.
When PS1 ends with a bare '%' (e.g. `%3~ %`), concatenating our 133;B
mark (`%{...%}`) directly after it causes zsh's prompt expansion to
interpret the '%' + '{' result as a '%{' escape sequence. This swallows
the 133;B mark and produces a visible '{' in the prompt.
Work around this by doubling a trailing '%' into '%%' before appending
marks, so it expands to a literal '%' and won't merge with the `%{`
token.
Each C API file independently imported ../../lib/allocator.zig as
lib_alloc. Now that terminal/lib.zig re-exports the allocator module
as lib.alloc, use that instead. This removes the redundant import
and keeps all lib dependencies flowing through the single lib.zig
entry point.
Previously every file in the terminal package independently imported
build_options and ../lib/main.zig, then computed the same
lib_target constant. This was repetitive and meant each file needed
both imports just to get the target.
Introduce src/terminal/lib.zig which computes the target once and
re-exports the commonly used lib types (Enum, TaggedUnion, Struct,
String, checkGhosttyHEnum, structSizedFieldFits). All terminal
package files now import lib.zig and use lib.target instead of the
local lib_target constant, removing the per-file boilerplate.
The resize function now requires cell_width_px and cell_height_px
parameters and handles the full resize sequence: computing and
setting width_px/height_px on the terminal, clearing synchronized output mode
so changes display immediately, and encoding a mode 2048 in-band size report
via the write_pty callback when that mode is enabled.
A valid width/height px is critical for some applications and protocols
and some applications rely directly on in-band size reports, so this
change is necessary to support those use cases.
Add total_rows and scrollback_rows as new TerminalData variants
queryable through the existing ghostty_terminal_get interface, using the
cached O(1) total_rows field from PageList rather than introducing
standalone functions.
Add total_rows and scrollback_rows as new TerminalData variants
queryable through the existing ghostty_terminal_get interface,
using the cached O(1) total_rows field from PageList rather than
introducing standalone functions.
Previously ghostty_terminal_set required all values to be passed as
pointers to the value, even when the value itself was already a
pointer (userdata, function pointer callbacks). This forced callers
into awkward patterns like compound literals or intermediate
variables just to take the address of a pointer.
Now pointer-typed options (userdata and all callbacks) are passed
directly as the value parameter. Only non-pointer types like
GhosttyString still require a pointer to the value. This
simplifies InType to return the actual stored type for each option
and lets setTyped work with those types directly.
Add title and pwd as both gettable data keys
(GHOSTTY_TERMINAL_DATA_TITLE/PWD) and settable options
(GHOSTTY_TERMINAL_OPT_TITLE/PWD) in the C terminal API. Getting
returns a borrowed GhosttyString; setting copies the data into the
terminal via setTitle/setPwd.
The underlying Terminal.setTitle/setPwd now append a null sentinel so
that getTitle/getPwd can return sentinel-terminated slices ([:0]const
u8), which is useful for downstream consumers that need C strings.
Change ghostty_terminal_set to return GhosttyResult instead of void
so that the new title/pwd options can report allocation failures.
Existing option-setting calls cannot fail so the return value is
backwards-compatible for callers that discard it.
### This is it! This one (and the other stacked PRs) and #11782 should
finally give a clean test run on Windows!
## Summary
- Increase `@setEvalBranchQuota` from 1M to 10M (too much? how much is
too much?) in `checkGhosttyHEnum` (src/lib/enum.zig)
- Fixes the only remaining test failure on Windows MSVC: `ghostty.h
MouseShape`
## Context
This one was fun! Claude started blabbering, diminishing returns it
said. It couldn't figure out. So I called Dario and it worked.
Nah, much easier than that.
On MSVC, the translate-c output for `ghostty.h` is ~360KB with ~2173
declarations (vs ~112KB / ~1502 on Linux/Mac) because `<sys/types.h>`
and `<BaseTsd.h>` pull in Windows SDK headers. The `checkGhosttyHEnum`
function uses a nested `inline for` (enum fields x declarations) with
comptime string comparisons. For MouseShape (34 variants), this
generates roughly 34 x 2173 x ~20 = ~1.5M comptime branches, exceeding
the 1M quota.
The failure was confusing because it presented as a runtime error
("ghostty.h is missing value for GHOSTTY_MOUSE_SHAPE_DEFAULT") rather
than a compile error. The constants exist in the translate-c output and
the test compiles, but the comptime loop silently stops matching when it
hits the branch limit, so `set.remove` is never called and the set
reports all entries as missing at runtime.
## How we found it
The translate-c output clearly had all 34 GHOSTTY_MOUSE_SHAPE_*
constants, yet the test reported all of them as missing. I asked Claude
to list 5 hypotheses (decl truncation, branch quota, string comparison
bug, declaration ordering, field access failure) and to write 7 targeted
POC tests in enum.zig to isolate each step of `checkGhosttyHEnum`:
1. POC1-2: Module access and declaration count (both passed)
2. POC3: `@hasDecl` for the constant (passed)
3. POC4: Direct field value access (passed)
4. POC5: `inline for` over decls with string comparison - **compile
error: "evaluation exceeded 1000 backwards branches"**
5. POC6: Same but with 10M quota (passed)
6. POC7: Full `checkGhosttyHEnum` clone with 10M quota - **passed,
confirming the fix**
POC5 was the key: the default 1000 branch limit for test code confirmed
the comptime budget mechanism. The existing 1M quota in
`checkGhosttyHEnum` was enough for Linux/Mac (1502 declarations) but not
for MSVC (2173 declarations) with larger enums.
## Stack
Stacked on 016-windows/fix-libcxx-msvc.
## Test plan
### Cross-platform results (`zig build test` / `zig build
-Dapp-runtime=none test` on Windows)
| | Windows | Linux | Mac |
|---|---|---|---|
| **BEFORE** (016, ce9930051) | FAIL - 49/51, 2630/2654, 1 test failed,
23 skipped | PASS - 86/86, 2655/2678, 23 skipped | PASS - 160/160,
2655/2662, 7 skipped |
| **AFTER** (017, 68378a0bb) | FAIL - 49/51, 2631/2654, 23 skipped |
PASS - 86/86, 2655/2678, 23 skipped | PASS - 160/160, 2655/2662, 7
skipped |
### Windows: what changed (2630 -> 2631 tests, MouseShape fixed)
**Fixed by this PR:**
- `ghostty.h MouseShape` test - was failing because comptime branch
quota exhaustion silently prevented the inline for loop from matching
any constants
**Remaining failure (pre-existing, unrelated):**
- `config.Config.test.clone can then change conditional state` -
segfaults (exit code 3) on Windows. We investigated this and it looked
familiar.. cherry-picking the `CommaSplitter `fix from PR #11782
resolved it! The backslash path handling in `CommaSplitter `breaks theme
path parsing on Windows, which is exactly what that PR addresses. So
once that lands, we should be in a good place... ready to ship to
Windows users! (just kidding)
### Linux/macOS: no regressions
Identical pass counts and test results before and after.
## What I Learnt
- Comptime branch quota exhaustion in Zig does not always surface as a
clean compile error. When it happens inside an `inline for` loop with
`comptime` string comparisons that gate runtime code (like
`set.remove`), the effect is that matching code is silently not
generated. The test compiles and runs, but the runtime behavior is wrong
because the matching branches were never emitted. This makes the failure
look like a data issue (missing declarations) rather than a compile
budget issue.
- When debugging comptime issues, writing small isolated POC tests that
exercise each step of the failing function independently is very
effective. It took 7 targeted tests to pinpoint the exact failure point.
- Cross-platform translate-c outputs can vary significantly in size. On
MSVC, system headers are much larger than on Linux/Mac, which affects
comptime budgets for any code that iterates over translated module
declarations.
Replace the O(N×M) nested inline for loop with direct @hasDecl lookups.
The old approach iterated over all translate-c declarations for each enum
field, which required a 10M comptime branch quota on MSVC (2173 decls ×
138 fields × ~20 branches). The new approach constructs the expected
declaration name and checks directly, reducing to O(N) and needing only
100K quota on all platforms.
Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
The DA1 trampoline was converting C feature codes into a local
stack buffer and returning a slice pointing into it. This is
unsound because the slice outlives the stack frame once the
trampoline returns, leaving reportDeviceAttributes reading
invalid memory.
Move the scratch buffer into the wrapper effects struct so that
its lifetime extends beyond the trampoline call, keeping the
returned slice valid for the caller.
