pty

README

Go Pty

Go-Pty is a package for using pseudo-terminal interfaces in Go. It supports Unix PTYs and Windows through ConPty.

Why can't we just use os/exec?

Windows requires updating the process running in the PTY with a special attribute to enable ConPty support. This is not possible with os/exec see go#62708 and go#6271. On Unix, pty.Cmd is just a wrapper around os/exec.Cmd that sets up the PTY.

Usage

go get github.com/aymanbagabas/go-pty

Example running grep

package main

import (
	"io"
	"log"
	"os"

	"github.com/aymanbagabas/go-pty"
)

func main() {
	pty, err := pty.New()
	if err != nil {
		log.Fatalf("failed to open pty: %s", err)
	}

	defer pty.Close()
	c := pty.Command("grep", "--color=auto", "bar")
	if err := c.Start(); err != nil {
		log.Fatalf("failed to start: %s", err)
	}

	go func() {
		pty.Write([]byte("foo\n"))
		pty.Write([]byte("bar\n"))
		pty.Write([]byte("baz\n"))
		pty.Write([]byte{4}) // EOT
	}()
	go io.Copy(os.Stdout, pty)

	if err := c.Wait(); err != nil {
		panic(err)
	}
}

Refer to ./examples for more examples.

Credits

• creack/pty: support for Unix PTYs
• microsoft/hcsshim: Windows ConPty implementation

License

This project is licensed under the MIT License - see the LICENSE for details.

Documentation

Index

• Variables
• func ApplyTerminalModes(fd int, width int, height int, modes ssh.TerminalModes) error
• type Cmd
  • func (c *Cmd) Run() error
  • func (c *Cmd) Start() error
  • func (c *Cmd) Wait() error
• type ConPty
• type Pty
  • func New() (Pty, error)
• type UnixPty
• type Winsize

Variables

var (
	// ErrInvalidCommand is returned when the command is invalid.
	ErrInvalidCommand = errors.New("pty: invalid command")

	// ErrUnsupported is returned when the platform is unsupported.
	ErrUnsupported = errors.New("pty: unsupported platform")
)

Functions

func ApplyTerminalModes

func ApplyTerminalModes(fd int, width int, height int, modes ssh.TerminalModes) error

ApplyTerminalModes applies the given ssh terminal modes to the given file descriptor.

Types

type Cmd

type Cmd struct {

	// Path is the path of the command to run.
	Path string

	// Args holds command line arguments, including the command as Args[0].
	Args []string

	// Env specifies the environment of the process.
	// If Env is nil, the new process uses the current process's environment.
	Env []string

	// Dir specifies the working directory of the command.
	// If Dir is the empty string, the current directory is used.
	Dir string

	// SysProcAttr holds optional, operating system-specific attributes.
	SysProcAttr *syscall.SysProcAttr

	// Process is the underlying process, once started.
	Process *os.Process

	// ProcessState contains information about an exited process.
	// If the process was started successfully, Wait or Run will populate this
	// field when the command completes.
	ProcessState *os.ProcessState

	// Cancel is called when the command is canceled.
	Cancel func() error
	// contains filtered or unexported fields
}

Cmd is a command that can be started attached to a pseudo-terminal. This is similar to the API of exec.Cmd. The main difference is that the command is started attached to a pseudo-terminal. This is required as we cannot use exec.Cmd directly on Windows due to limitation of starting a process attached to a pseudo-terminal. See: https://github.com/golang/go/issues/62708

func (*Cmd) Run

func (c *Cmd) Run() error

Run runs the command and waits for it to complete.

func (*Cmd) Start

func (c *Cmd) Start() error

Start starts the specified command attached to the pseudo-terminal.

func (*Cmd) Wait

func (c *Cmd) Wait() error

Wait waits for the command to exit.

type ConPty

type ConPty interface {
	Pty

	// InputPipe returns the ConPty input pipe.
	InputPipe() *os.File

	// OutputPipe returns the ConPty output pipe.
	OutputPipe() *os.File
}

ConPty is a Windows ConPTY interface.

type Pty

type Pty interface {
	io.ReadWriteCloser

	// Name returns the name of the pseudo-terminal.
	// On Windows, this will always be "windows-pty".
	// On Unix, this will return the name of the slave end of the
	// pseudo-terminal TTY.
	Name() string

	// Command returns a command that can be used to start a process
	// attached to the pseudo-terminal.
	Command(name string, args ...string) *Cmd

	// CommandContext returns a command that can be used to start a process
	// attached to the pseudo-terminal.
	CommandContext(ctx context.Context, name string, args ...string) *Cmd

	// Resize resizes the pseudo-terminal.
	Resize(width int, height int) error

	// Fd returns the file descriptor of the pseudo-terminal.
	// On Unix, this will return the file descriptor of the master end.
	// On Windows, this will return the handle of the console.
	Fd() uintptr
}

Pty is a pseudo-terminal interface.

func New

func New() (Pty, error)

New returns a new pseudo-terminal.

type UnixPty

type UnixPty interface {
	Pty

	// Master returns the pseudo-terminal master end (pty).
	Master() *os.File

	// Slave returns the pseudo-terminal slave end (tty).
	Slave() *os.File

	// Control calls f on the pseudo-terminal master end (pty).
	Control(f func(fd uintptr)) error

	// SetWinsize sets the pseudo-terminal window size.
	SetWinsize(ws *Winsize) error
}

UnixPty is a Unix pseudo-terminal interface.

type Winsize

type Winsize = unix.Winsize

Winsize represents the terminal window size.