# Google Gvisor Gvisor > Add or extend syscall: `$target` - Skill: `tomevault-io/google-gvisor-gvisor` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add tomevault-io/google-gvisor-gvisor` - Raw SKILL.md: https://api.skillmd.com/api/skills/tomevault-io/google-gvisor-gvisor/raw - Safety review: pending (external: skill-scanner PASS, skillspector PASS) - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: tomevault-io (https://skillmd.com/u/tomevault-io) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/tomevault-io/google-gvisor-gvisor --- # Add or extend syscall: `$target` You are adding or extending Linux syscall support in gvisor. The target is: **$target** ## Phase 1: Understand the current state 1. **Check the syscall table** — search `pkg/sentry/syscalls/linux/linux64.go` for the syscall name. Determine: - Is it registered? (has a table entry) - What is its support level? (`Supported`, `PartiallySupported`, `ErrorWithEvent`, `Error`) - What handler function is it mapped to? 2. **Read the existing implementation** (if any) — find the handler in `pkg/sentry/syscalls/linux/sys_*.go`. Look for: - Which flags/options are already handled - Which flags fall through to `default:` / return `EINVAL` / `ENOSYS` - The function signature pattern: `func Name(t *kernel.Task, sysno uintptr, args arch.SyscallArguments) (uintptr, *kernel.SyscallControl, error)` 3. **Check existing ABI constants** — look in `pkg/abi/linux/` for the relevant constants file (e.g., `prctl.go`, `ioctl.go`, `socket.go`) 4. **Read the Linux man page / kernel source** — use WebSearch or WebFetch to look up the exact Linux behavior for the syscall or flag. This is critical for correctness. Search for the man page (e.g., `man 2 prctl`) and/or relevant kernel source. ## Phase 2: Plan the changes Present the user a summary before writing code: - What the target syscall/flag does in Linux - What changes are needed in gvisor (list files) - Any kernel subsystems that need new support (e.g., new task fields, VFS operations) - Whether this can be a simple implementation or needs deeper infrastructure Wait for user confirmation before proceeding. ## Phase 3: Implement Follow this checklist — not all steps apply to every change: ### A. ABI Constants (`pkg/abi/linux/`) - Add any missing constants to the appropriate file - Follow the existing naming convention (e.g., `PR_` prefix for prctl, `CLONE_` for clone flags) - Add a one-line comment matching the Linux kernel comment style: `// PR_FOO does bar.` - If adding a new struct, use `pkg/marshal` for user-space copying ### B. Syscall Implementation (`pkg/sentry/syscalls/linux/sys_*.go`) - **New syscall**: Create `sys_.go` with the handler function. Follow the standard signature: ```go func SyscallName(t *kernel.Task, sysno uintptr, args arch.SyscallArguments) (uintptr, *kernel.SyscallControl, error) { ``` - **New flag on existing syscall**: Add a `case` to the existing switch statement - Use `linuxerr` package for errors (e.g., `linuxerr.EINVAL`, `linuxerr.EPERM`) - Use `t.CopyIn*` / `t.CopyOut*` or `primitive.Copy*` for userspace memory access - Use `hostarch.Addr` for user pointers: `args[N].Pointer()` - Use `args[N].Int()`, `args[N].Uint()`, `args[N].Uint64()` for scalar arguments ### C. Syscall Table (`pkg/sentry/syscalls/linux/linux64.go`) - **New syscall**: Change from `syscalls.ErrorWithEvent(...)` or `syscalls.Error(...)` to `syscalls.Supported("name", HandlerFunc)` or `syscalls.PartiallySupported("name", HandlerFunc, "note about limitations", nil)` - **Improved existing**: Update `PartiallySupported` note to reflect newly supported options, or upgrade to `Supported` if fully implemented - The table has entries for both AMD64 and ARM64 — update both if the syscall applies to both architectures ### D. BUILD files - Add new `.go` files to `srcs` in `pkg/sentry/syscalls/linux/BUILD` - Add any new package dependencies to `deps` - Add new ABI files to `pkg/abi/linux/BUILD` if created ### E. Kernel/Sentry Support (if needed) - New task-level state → `pkg/sentry/kernel/task.go` or related - New filesystem operations → `pkg/sentry/vfs/` or `pkg/sentry/fsimpl/` - New network features → `pkg/tcpip/` ### F. Tests (`test/syscalls/linux/`) - Add or extend C++ tests in `test/syscalls/linux/.cc` - Use the gtest framework with gvisor's test utilities: - `SyscallSucceeds()`, `SyscallFailsWithErrno(EINVAL)`, etc. from `test/util/test_util.h` - `ASSERT_NO_ERRNO_AND_VALUE()` for operations that return PosixErrorOr - Add test to `test/syscalls/linux/BUILD` if it's a new file - Test both the happy path and error cases ## Phase 4: Test-driven verification against native Linux The test MUST pass on native Linux first. This ensures the test itself is correct before running it inside gvisor. Native test targets run the C++ test binary directly on the host kernel. ### Step 1: Run the native test The native test target naming convention is: ``` bazel test //test/syscalls:_test_native ``` For example: ``` bazel test //test/syscalls:access_test_native bazel test //test/syscalls:prctl_test_native bazel test //test/syscalls:eventfd_test_native ``` The native target is auto-generated by the `syscall_test()` macro in `test/syscalls/BUILD` from the `cc_binary` in `test/syscalls/linux/BUILD`. It runs with `--platform=native` (directly on the host kernel, no gvisor sandbox). **Run the native test FIRST and iterate until it passes.** If the native test fails, the test itself is buggy — fix the test before touching the gvisor implementation. ```bash bazel test //test/syscalls:_test_native --test_output=errors ``` To run a specific test case: ```bash bazel test //test/syscalls:_test_native --test_output=errors --test_arg=--gtest_filter='TestSuite.TestCase' ``` ### Step 2: Build the gvisor implementation After the native test passes, verify the gvisor code compiles: ```bash bazel build //pkg/sentry/syscalls/linux/... ``` If ABI constants changed: ```bash bazel build //pkg/abi/linux/... ``` ### Step 3: Run the gvisor (runsc) test After the native test passes and the gvisor implementation compiles, run the test under gvisor to verify the implementation is correct: ```bash bazel test //test/syscalls:_test_runsc_ptrace_shared --test_output=errors ``` This test MUST pass. If it fails, the gvisor implementation has a bug — fix the implementation and re-run until it passes. ### Iterative workflow The expected loop is: 1. Write/update the C++ test in `test/syscalls/linux/.cc` 2. Run `bazel test //test/syscalls:_test_native --test_output=errors` 3. If it fails → fix the test (it's a bug in the test, not Linux) 4. Once native passes → implement/update the gvisor handler 5. Build gvisor: `bazel build //pkg/sentry/syscalls/linux/...` 6. Run `bazel test //test/syscalls:_test_runsc_ptrace_shared --test_output=errors` 7. If it fails → fix the gvisor implementation and repeat from step 5 ## Key patterns to follow ### Error handling ```go // Return Linux error codes from linuxerr package return 0, nil, linuxerr.EINVAL return 0, nil, linuxerr.EPERM return 0, nil, linuxerr.ENOSYS ``` ### Copying data to/from userspace ```go // Copy a single int32 to userspace _, err := primitive.CopyInt32Out(t, args[1].Pointer(), value) // Copy a struct from userspace var s SomeStruct _, err := s.CopyIn(t, args[0].Pointer()) // Copy a string from userspace name, err := t.CopyInString(addr, maxLen) ``` ### Unimplemented options pattern ```go // For options you deliberately don't implement, emit an event: t.Kernel().EmitUnimplementedEvent(t, sysno) return 0, nil, linuxerr.ENOSYS ``` ### Credential checks ```go creds := t.Credentials() if !creds.HasCapabilityIn(linux.CAP_SYS_ADMIN, creds.UserNamespace) { return 0, nil, linuxerr.EPERM } ``` ## Important notes - Match Linux behavior exactly — check the man page and kernel source for edge cases - gvisor does NOT have a real kernel, so some things (hardware access, kernel modules) cannot be implemented — stub them with appropriate errors - Always handle the `default:` case in switch statements - Use `t.Kernel().EmitUnimplementedEvent(t, sysno)` before returning ENOSYS for deliberate non-implementation — this enables tracking of missing features - Prefer returning errors over panicking - Consider both amd64 and arm64 when the syscall exists on both architectures --- > Source: [google/gvisor](https://github.com/google/gvisor) — distributed by [TomeVault](https://tomevault.io).