pty

README

Go Pty

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

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
  • func (p *ConPty) Close() error
  • func (p *ConPty) Command(name string, args ...string) *Cmd
  • func (p *ConPty) CommandContext(ctx context.Context, name string, args ...string) *Cmd
  • func (p *ConPty) Fd() uintptr
  • func (*ConPty) Name() string
  • func (p *ConPty) Read(b []byte) (n int, err error)
  • func (p *ConPty) Resize(width int, height int) error
  • func (p *ConPty) Write(b []byte) (n int, err error)
• type Pty
  • func New() (Pty, error)

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 struct {
	// contains filtered or unexported fields
}

ConPty is a Windows console pseudo-terminal. It uses Windows pseudo console API to create a console that can be used to start processes attached to it.

See: https://docs.microsoft.com/en-us/windows/console/creating-a-pseudoconsole-session

func (*ConPty) Close

func (p *ConPty) Close() error

Close implements Pty.

func (*ConPty) Command

func (p *ConPty) Command(name string, args ...string) *Cmd

Command implements Pty.

func (*ConPty) CommandContext

func (p *ConPty) CommandContext(ctx context.Context, name string, args ...string) *Cmd

CommandContext implements Pty.

func (*ConPty) Fd

func (p *ConPty) Fd() uintptr

Fd implements Pty.

func (*ConPty) Name

func (*ConPty) Name() string

Name implements Pty.

func (*ConPty) Read

func (p *ConPty) Read(b []byte) (n int, err error)

Read implements Pty.

func (*ConPty) Resize

func (p *ConPty) Resize(width int, height int) error

Resize implements Pty.

func (*ConPty) Write

func (p *ConPty) Write(b []byte) (n int, err error)

Write implements Pty.

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.