Docs/Standard library

term

Query terminal dimensions, detect terminal streams, read passwords without echo, and enter or restore raw mode.

Terminal utilities#

Import term to interact with a terminal through an open os.File. For example, obtain standard input with os.Stdin().unwrap(). Every function accepts the file itself, rather than its integer native handle or the Result<os.File> returned by os.Stdin(). Native descriptors can be adopted with os.FromDescriptor. The package does not close the supplied file.

All five functions return Result values. Inspect the error variant to recover, or call .unwrap() to panic on failure. Successful MakeRaw and Restore calls return true.

Terminal utilities reference
SignatureBehavior
GetSize(file os.File) Result<Size>Returns the terminal width and height in character cells.
IsTerminal(file os.File) Result<bool>Reports whether an open file is a terminal; invalid descriptors return errors.
ReadPassword(file os.File) Result<string>Reads a line without echo and restores the previous settings.
MakeRaw(file os.File) Result<bool>Saves the original settings and enables raw mode.
Restore(file os.File) Result<bool>Restores the settings saved by MakeRaw.

term.Size and term.GetSize#

Size is a struct in the term package with two exported int fields: Width is the number of columns and Height is the number of rows. GetSize queries the current dimensions, so call it again after a resize when adapting a layout. These dimensions describe character cells rather than pixels.

The query uses the terminal associated with the supplied file. Redirected files and pipes do not have terminal dimensions and return an error. Closed files, invalid descriptors, native failures, and unsupported targets also return errors.

Ocean
package main;
import "io";
import "os";
import "term";

func main() {
    input := os.Stdin().unwrap();
    size := term.GetSize(input).unwrap();
    io.Println(size.Width, " columns, ", size.Height, " rows").unwrap();
}

The type is equivalent to struct Size { Width int; Height int; }. On Windows, dimensions describe the visible console window rather than its scrollback buffer.

term.IsTerminal#

IsTerminal(file os.File) Result<bool> succeeds with true for a terminal and false for a valid regular file or pipe. A closed file or invalid native descriptor produces an error rather than false. Other native failures and unsupported targets also produce errors.

Check the stream you intend to use: stdin and stdout can be redirected independently. For example, a command can read from a terminal while writing to a file.

Ocean
package main;
import "io";
import "os";
import "term";

func main() {
    output := os.Stdout().unwrap();
    match(term.IsTerminal(output)) {
        Result<bool>.value(terminal) => io.Println("Terminal output: ", terminal).unwrap();
        Result<bool>.error(message) => io.Println("Terminal check failed: ", message).unwrap();
    }
}

term.ReadPassword#

ReadPassword(file os.File) Result<string> reads one line from a readable terminal without echoing its characters. It consumes the terminating newline and returns the password without that newline. It prints neither a prompt nor a newline, so the caller supplies both when desired. Canonical line input preserves terminal erase processing. EOF succeeds with the bytes read so far, including an empty string.

The function saves the current settings and restores them after success, EOF, or a read error, and attempts restoration during ordinary panic unwinding. A restoration failure returns an error. If the terminal was already in raw mode, that raw state is restored without changing the state saved for a later Restore call.

Nonreadable files, nonterminal streams, closed or invalid descriptors, native failures, and unsupported targets return errors. Avoid mixing this direct input with a buffered scanner on the same stream.

Ocean
package main;
import "io";
import "os";
import "term";

func main() {
    input := os.Stdin().unwrap();
    io.Print("Password: ").unwrap();
    password := term.ReadPassword(input).unwrap();
    io.Println().unwrap();
    // Use password without printing it.
}

term.MakeRaw and term.Restore#

MakeRaw(file os.File) Result<bool> saves the original settings and enables raw mode. Raw mode disables line buffering, echo, terminal signal-key processing, and output processing on Unix. A read can receive input without waiting for Enter. Windows uses console input mode flags, including virtual-terminal input.

Restore(file os.File) Result<bool> restores the settings saved by MakeRaw. Both functions return true on success and an error on failure. Repeated successful MakeRaw calls preserve the first saved settings; one successful Restore restores them and clears the saved entry. Calling Restore without saved settings returns an error. A failed restoration retains the saved entry so it can be retried.

Restore before closing the file. Copies of an os.File share the terminal and its saved settings, and callers must coordinate changes to the same terminal.

Ocean
package main;
import "os";
import "term";

func restore(input os.File) {
    term.Restore(input).unwrap();
}

func main() {
    input := os.Stdin().unwrap();
    term.MakeRaw(input).unwrap();
    defer restore(input);
    key := input.Readchunk(1).unwrap();
    // Process key; the deferred helper restores the terminal on exit.
}

Defer a helper that calls Restore, as shown above. In defer term.Restore(input).unwrap();, the receiver expression would call Restore immediately and only defer the final unwrap call.

Platform support#

Native bindings use Linux terminal ioctls on x86-64, AArch64, and RISC-V64; Darwin terminal ioctls on x86-64 and AArch64; and Win32 console APIs on x86-64 and AArch64. Other targets return unsupported errors.

Runtime integration tests currently cover Linux pseudoterminals, including resize queries, raw-mode restoration, password echo suppression and line editing, EOF, read failures, pipes, regular files, and invalid or closed descriptors. macOS and Windows bindings have not yet been runtime-tested.