README

console

PkgGoDev Build Status Go Report Card

Golang package for dealing with consoles. Light on deps and a simple API.

Modifying the current process

current := console.Current()
defer current.Reset()

if err := current.SetRaw(); err != nil {
}
ws, err := current.Size()
current.Resize(ws)

Project details

console is a containerd sub-project, licensed under the Apache 2.0 license. As a containerd sub-project, you will find the:

information in our containerd/project repository.

Documentation

Index

Constants

This section is empty.

Variables

View Source
var ErrNotAConsole = errors.New("provided file is not a console")

Functions

func ClearONLCR

func ClearONLCR(fd uintptr) error

    ClearONLCR sets the necessary tty_ioctl(4)s to ensure that a pty pair created by us acts normally. In particular, a not-very-well-known default of Linux unix98 ptys is that they have +onlcr by default. While this isn't a problem for terminal emulators, because we relay data from the terminal we also relay that funky line discipline.

    func SetONLCR

    func SetONLCR(fd uintptr) error

      SetONLCR sets the necessary tty_ioctl(4)s to ensure that a pty pair created by us acts as intended for a terminal emulator.

      Types

      type Console

      type Console interface {
      	File
      
      	// Resize resizes the console to the provided window size
      	Resize(WinSize) error
      	// ResizeFrom resizes the calling console to the size of the
      	// provided console
      	ResizeFrom(Console) error
      	// SetRaw sets the console in raw mode
      	SetRaw() error
      	// DisableEcho disables echo on the console
      	DisableEcho() error
      	// Reset restores the console to its orignal state
      	Reset() error
      	// Size returns the window size of the console
      	Size() (WinSize, error)
      }

      func ConsoleFromFile

      func ConsoleFromFile(f File) (Console, error)

        ConsoleFromFile returns a console using the provided file nolint:golint

        func Current

        func Current() (c Console)

          Current returns the current process' console

          func NewPty

          func NewPty() (Console, string, error)

            NewPty creates a new pty pair The master is returned as the first console and a string with the path to the pty slave is returned as the second

            type EpollConsole

            type EpollConsole struct {
            	Console
            	// contains filtered or unexported fields
            }

              EpollConsole acts like a console but registers its file descriptor with an epoll fd and uses epoll API to perform I/O.

              func (*EpollConsole) Read

              func (ec *EpollConsole) Read(p []byte) (n int, err error)

                Read reads up to len(p) bytes into p. It returns the number of bytes read (0 <= n <= len(p)) and any error encountered.

                If the console's read returns EAGAIN or EIO, we assume that it's a temporary error because the other side went away and wait for the signal generated by epoll event to continue.

                func (*EpollConsole) Shutdown

                func (ec *EpollConsole) Shutdown(close func(int) error) error

                  Shutdown closes the file descriptor and signals call waiters for this fd. It accepts a callback which will be called with the console's fd. The callback typically will be used to do further cleanup such as unregister the console's fd from the epoll interface. User should call Shutdown and wait for all I/O operation to be finished before closing the console.

                  func (*EpollConsole) Write

                  func (ec *EpollConsole) Write(p []byte) (n int, err error)

                    Writes len(p) bytes from p to the console. It returns the number of bytes written from p (0 <= n <= len(p)) and any error encountered that caused the write to stop early.

                    If writes to the console returns EAGAIN or EIO, we assume that it's a temporary error because the other side went away and wait for the signal generated by epoll event to continue.

                    type Epoller

                    type Epoller struct {
                    	// contains filtered or unexported fields
                    }

                      Epoller manages multiple epoll consoles using edge-triggered epoll api so we dont have to deal with repeated wake-up of EPOLLER or EPOLLHUP. For more details, see: - https://github.com/systemd/systemd/pull/4262 - https://github.com/moby/moby/issues/27202

                      Example usage of Epoller and EpollConsole can be as follow:

                      epoller, _ := NewEpoller()
                      epollConsole, _ := epoller.Add(console)
                      go epoller.Wait()
                      var (
                      	b  bytes.Buffer
                      	wg sync.WaitGroup
                      )
                      wg.Add(1)
                      go func() {
                      	io.Copy(&b, epollConsole)
                      	wg.Done()
                      }()
                      // perform I/O on the console
                      epollConsole.Shutdown(epoller.CloseConsole)
                      wg.Wait()
                      epollConsole.Close()
                      

                      func NewEpoller

                      func NewEpoller() (*Epoller, error)

                        NewEpoller returns an instance of epoller with a valid epoll fd.

                        func (*Epoller) Add

                        func (e *Epoller) Add(console Console) (*EpollConsole, error)

                          Add creates an epoll console based on the provided console. The console will be registered with EPOLLET (i.e. using edge-triggered notification) and its file descriptor will be set to non-blocking mode. After this, user should use the return console to perform I/O.

                          func (*Epoller) Close

                          func (e *Epoller) Close() error

                            Close closes the epoll fd

                            func (*Epoller) CloseConsole

                            func (e *Epoller) CloseConsole(fd int) error

                              CloseConsole unregisters the console's file descriptor from epoll interface

                              func (*Epoller) Wait

                              func (e *Epoller) Wait() error

                                Wait starts the loop to wait for its consoles' notifications and signal appropriate console that it can perform I/O.

                                type File

                                type File interface {
                                	io.ReadWriteCloser
                                
                                	// Fd returns its file descriptor
                                	Fd() uintptr
                                	// Name returns its file name
                                	Name() string
                                }

                                type WinSize

                                type WinSize struct {
                                	// Height of the console
                                	Height uint16
                                	// Width of the console
                                	Width uint16
                                	// contains filtered or unexported fields
                                }

                                  WinSize specifies the window size of the console