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
• 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")
)

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.