gameproc

README

go-gameproc

---

Find, stop and wait for a game's processes, natively or under Wine, Proton, dotnet or mono, on Linux and Windows. Package gameproc, module github.com/Rethunk-Tech/go-gameproc.

A launcher or mod manager must tell which install a process belongs to, never mistake a system program or Steam for the game, and stop it cleanly. This package does that from the process table alone: no game data, no options, names come from the caller.

Quick start

go get github.com/Rethunk-Tech/go-gameproc

A worked example and the contracts: HUMANS.md.

Features

• List processes by program name in one pass, with executable, command line and start time, including from inside a Flatpak.
• Tell which install a process runs from, by executable, argument, Wine Z: path or symlinked deploy.
• Stop politely: a Wine process is asked to close first, so a launcher sees a clean exit.
• Wait for any pid, and read the exit code and signal of a child.
• Start a child so its whole tree ends together: a process group, or a job object on Windows.
• Start a Windows console program in a console of its own.

Documentation

Doc	Audience
HUMANS.md	Running and using the package
AGENTS.md	Internals, invariants, and why
CONTRIBUTING.md	Process — commits, tests, docs
SECURITY.md	Vulnerability disclosure
CHANGELOG.md	Release notes

License

MIT — see LICENSE. © 2026 Rethunk.Tech, LLC.

Documentation

Overview

Package gameproc finds, stops and waits for a game's processes, natively or under Wine, Proton, dotnet or mono, on Linux (including from inside a Flatpak) and Windows.

Index

• Variables
• func Alive(pid int) bool
• func ImagePath(pid int) (string, error)
• func KillTree(pid int)
• func PrepareTree(cmd *exec.Cmd, _ bool)
• func StartOwnConsole([]string, string, string, []string) (<-chan error, error)
• func Stop(ctx context.Context, p Process, grace time.Duration) error
• func Terminate(pid int, grace time.Duration) error
• func TrackTree(pid int) error
• func UntrackTree(int)
• type Process
  • func Processes(procDir string, names ...string) ([]Process, error)
  • func (p Process) ExeIs(names ...string) bool
  • func (p Process) LinkedFrom(dir string) bool
  • func (p Process) Named(names ...string) bool
  • func (p Process) RunsFrom(dir string) bool
• type Status
  • func StatusOf(waitErr error) Status
  • func WaitPID(pid int) (Status, error)

Variables

var ErrNoConsole = errors.New("gameproc: a program with its own console starts only on Windows")

ErrNoConsole is StartOwnConsole's error off Windows.

var ErrNotChild = errors.New("gameproc: the process is not a child, so its exit status is unknown")

ErrNotChild is WaitPID's error, joined with the wait error, for a Unix process that is not the caller's child: it was waited out, but its exit status is unknown.

var ErrNotTracked = errors.New("gameproc: the process runs outside a job")

ErrNotTracked is TrackTree's error, joined with its cause, for a process that was resumed but that no job holds: KillTree then ends only the process.

Functions

func Alive

func Alive(pid int) bool

Alive reports whether a process with this pid exists; a pid of 0 or less never does. In a Flatpak a failure to ask the host reads as false; callers that must tell the two apart (Stop, WaitPID) use hostProbe.

func ImagePath

func ImagePath(pid int) (string, error)

ImagePath is the executable of pid, read from /proc/<pid>/exe. It is an error where there is no /proc (macOS) and for a process the caller may not inspect. A deleted executable keeps the " (deleted)" suffix the kernel adds.

func KillTree

func KillTree(pid int)

KillTree sends SIGTERM to the process group PrepareTree made pid the leader of. It refuses pid 1 and below, since kill(-1, ...) signals every process the user owns.

func PrepareTree

func PrepareTree(cmd *exec.Cmd, _ bool)

PrepareTree puts the process in a group of its own, so KillTree can end it with everything it started. The noConsole argument has no effect off Windows. Any SysProcAttr the caller set is kept.

func StartOwnConsole

func StartOwnConsole([]string, string, string, []string) (<-chan error, error)

StartOwnConsole starts a program in a new console that it reads and writes itself. That exists only on Windows; elsewhere it returns ErrNoConsole.

func Stop

func Stop(ctx context.Context, p Process, grace time.Duration) error

Stop is Terminate, after asking a Wine process to close its windows first, as quitting it would: a program that registered with a running launcher (Steam) signs off only on a clean exit, and killed instead it stays listed under its Wine pid, which the launcher then waits on for good. Whatever is still running after grace is terminated. The polite close is skipped inside a Flatpak, where the process's environment is not readable.

func Terminate

func Terminate(pid int, grace time.Duration) error

Terminate asks the process to exit (SIGTERM) and kills it if it is still there after grace. A process that is already gone is success; one the caller may not signal is an error.

func TrackTree

func TrackTree(pid int) error

TrackTree needs nothing off Windows: the process group is complete at the start. It still refuses a pid no process has, so the same call is safe on every OS.

func UntrackTree

func UntrackTree(int)

UntrackTree is a no-op off Windows.

Types

type Process

type Process struct {
	PID   int
	Exe   string
	Args  []string
	Start time.Time
}

Process is a running process. Args is nil where the platform gives no command line (Windows). Exe is empty where the platform will not say which file the process runs (another user's process, a host listing from a Flatpak). Start is the zero time when unknown.

func Processes

func Processes(procDir string, names ...string) ([]Process, error)

Processes lists running processes whose program is one of names, in one pass over the process table. procDir is a /proc-shaped tree. Only the literal "/proc" inside a Flatpak lists the host's processes, through flatpak-spawn (which needs --talk-name=org.freedesktop.Flatpak); a fake tree is never sent to the host.

func (Process) ExeIs

func (p Process) ExeIs(names ...string) bool

ExeIs reports whether p's executable is one of the programs names, so its path is where the game itself runs from; it is false for an unreadable executable and for a host (Wine, Proton, dotnet) that runs the game.

func (Process) LinkedFrom

func (p Process) LinkedFrom(dir string) bool

LinkedFrom reports whether p's executable is the target of the file of the same name in dir. A mod manager that deploys by symlink puts the loader in the game folder as a link into its staging folder, and Windows names a process by the link's target, so the process path alone would not place it in the install.

func (Process) Named

func (p Process) Named(names ...string) bool

Named reports whether p is one of names, as Processes matched it.

func (Process) RunsFrom

func (p Process) RunsFrom(dir string) bool

RunsFrom reports whether p belongs to the install in dir: its executable is inside dir, or a command-line argument names a path inside it. Wine and Proton processes show the Windows path of the game, which sits under Z: for a file outside the prefix, so that form counts as the Unix path it maps to.

type Status

type Status struct {
	Code   int
	Signal string
}

Status is how a process ended. Signal is the Unix signal name ("SIGSEGV") of a process a signal killed, and is empty on Windows. A killed process has Code 128 plus the signal number.

func StatusOf

func StatusOf(waitErr error) Status

StatusOf maps exec.Cmd.Wait's error to a Status. A process killed by a signal has Code 128 plus the signal number and the signal's name in Signal. An error that is not an exit is Code 1.

func WaitPID

func WaitPID(pid int) (Status, error)

WaitPID waits until pid exits. The exit status is readable only for the caller's own child (os.FindProcess(pid).Wait()). For any other process it polls Alive until the exit and returns an empty Status and an error matching ErrNotChild, so a caller can tell an unknown exit from a clean one. Inside a Flatpak it returns a nil error once the host probe says the process is gone.