Documentation
¶
Overview ¶
Package gopty is a small, platform-neutral pty (pseudo terminal) backend: it starts a child process attached to a pty master and hands the caller a raw bidirectional byte stream, plus resize and exit-code wait.
Backends (see pty_unix.go / pty_windows.go):
- unix: github.com/creack/pty, whose master file is the stream.
- windows: a vendored copy of UserExistsError/conpty (./conpty, MIT), Win10 1809+. ConPTY takes ONE command-line string, so Start joins Command+Args into a safely quoted line (windows.EscapeArg); a caller-supplied Env is de-duplicated with the os/exec rule ("last occurrence wins") because CreateProcess keeps the first.
Both backends satisfy the same Pty contract, so a program that runs pty children compiles and behaves the same on a unix worker and on Windows.
A ConPTY child must be created through the ConPTY API rather than os/exec (golang/go#62708), and some Windows process contexts refuse it: suga's console harness (scripts/wincons) reported CreateProcess failing with STATUS_DLL_INIT_FAILED (0xC0000142) inside a gofer job, while this repo's own probe in a gofer job starts a ConPTY child fine (cmd.exe, exit 0) — so the outcome is environment-dependent. Treat it as possible: check IsHostBlocked / IsBlockedExitCode instead of assuming either way. When it is blocked, drive a real console for interactive work instead.
Interactive (test) children are best driven through the sibling package github.com/gookit/gopty/ptytest, which adds expect/send helpers on this contract.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func IsAvailable ¶
func IsAvailable() bool
IsAvailable probes the ConPTY API (Win10 1809+ / kernel32 pseudo-console procs).
func IsBlockedExitCode ¶
IsBlockedExitCode reports whether a child exit code means the host refused the ConPTY child instead of the command running (STATUS_DLL_INIT_FAILED): what a job object produces for a child it blocks. See IsHostBlocked.
func IsHostBlocked ¶
IsHostBlocked reports whether err means the OS refused a ConPTY child in this process context rather than the pty API being unusable: being inside a job object that does not allow breakaway makes CreateProcess fail (ERROR_ACCESS_DENIED) or the child die at load with STATUS_DLL_INIT_FAILED. Tests use it to skip with a clear reason (see ptytest) instead of reporting a bare error code.
Types ¶
type Pty ¶
type Pty interface {
io.ReadWriteCloser
// Resize sets the pty window size in character cells.
Resize(cols, rows int) error
// Wait blocks until the child exits (or ctx is cancelled) and returns the
// process exit code. A ctx cancellation returns a non-nil error without
// reaping; the caller kills via Close and calls Wait once.
Wait(ctx context.Context) (exitCode int, err error)
}
Pty is a running child attached to a pty master. Read/Write carry the raw byte stream to/from the child (stdout+stderr multiplexed on Read, stdin on Write); Resize sets the terminal window size; Wait blocks for the child to exit and returns its exit code. Close releases the master fd (and, on unix, kills the child) — teardown ORDER is owned by the caller's state machine, this type only provides the primitives.
type Spec ¶
type Spec struct {
Command string // executable to run
Args []string // args (not including argv[0])
Env []string // full process env (KEY=VALUE); nil = inherit os.Environ
Dir string // working directory; "" = inherit
Cols int // initial terminal width (columns); 0 = platform default
Rows int // initial terminal height (rows); 0 = platform default
}
Spec is a platform-neutral request to start a child under a pty.
Directories
¶
| Path | Synopsis |
|---|---|
|
Package conpty is the vendored Windows ConPTY backend (see conpty.go, which carries the //go:build windows constraint).
|
Package conpty is the vendored Windows ConPTY backend (see conpty.go, which carries the //go:build windows constraint). |
|
Package ptytest drives a program inside a pty from ordinary Go tests: start it, wait for the prompt, type, assert on the output, then shut it down.
|
Package ptytest drives a program inside a pty from ordinary Go tests: start it, wait for the prompt, type, assert on the output, then shut it down. |