Skip to content
CryoCryo home
Stdlibio

stdio

import std::io::stdio; · source

Three thin handles over file descriptors 0, 1, and 2, obtained from stdin(), stdout(), and stderr(). Each implements Read or Write and inherits every default on that trait. There is no buffering at this layer: stdout() translates to raw write(2) calls. Compose it explicitly with buf when you want it.

Types

Stdin

type struct Stdin {
    is_tty(&this) -> boolean;
    as_fd(&this) -> i32;
    lock(&this) -> StdinLock;
    line(mut &this) -> Result<Option<String>, IoError>;
    prompt(mut &this, prompt_msg: Str) -> Result<Option<String>, IoError>;
}
import std::io::stdio;

mut input: Stdin = stdin();
match (input.line()) {
    Result::Ok(Option::Some(text)) => { /* one line, newline stripped */ }
    Result::Ok(Option::None)       => { /* EOF */ }
    Result::Err(e)                 => { /* IoError */ }
}

Every handle carries is_tty(), as_fd(), and lock(). Stdin adds two conveniences: line() reads one line into an owned String with the newline stripped, and prompt(msg) writes the prompt to stderr — so it doesn't pollute piped stdout — then reads a line.

Methods

is_tty(&this) -> boolean;

True if stdin is attached to a terminal. False when piped, redirected, or closed.

as_fd(&this) -> i32;

Underlying file descriptor. Exposed for interop with code that still needs to pass fd 0 to a system call directly.

lock(&this) -> StdinLock;

Acquire the process-global stdin lock, blocking until it is free. The returned StdinLock reads through fd 0 and releases the lock on drop. See the module doc for the ownership rules.

line(mut &this) -> Result<Option<String>, IoError>;

Read one line of input and return it as an owned String with the trailing \n (and a preceding \r, if any) stripped. None means EOF before any bytes were read.

prompt(mut &this, prompt_msg: Str) -> Result<Option<String>, IoError>;

Write prompt_msg to stderr and read one line from stdin, trailing newline stripped. The prompt goes to stderr (not stdout) so piping the program's output doesn't capture the prompt text, the convention every well-behaved CLI follows.

Stdout and Stderr

type struct Stdout {
    is_tty(&this) -> boolean;
    as_fd(&this) -> i32;
    lock(&this) -> StdoutLock;
}
type struct Stderr {
    is_tty(&this) -> boolean;
    as_fd(&this) -> i32;
    lock(&this) -> StderrLock;
}

The two write handles, identical in shape. eprint and friends in fmt write through Stderr.

Stdout

Methods
is_tty(&this) -> boolean;
as_fd(&this) -> i32;
lock(&this) -> StdoutLock;

Acquire the process-global stdout lock, blocking until it is free. The returned StdoutLock writes through fd 1 and releases the lock on drop. See the module doc for the ownership rules.

Stderr

Methods
is_tty(&this) -> boolean;
as_fd(&this) -> i32;
lock(&this) -> StderrLock;

Acquire the process-global stderr lock, blocking until it is free. The returned StderrLock writes through fd 2 and releases the lock on drop. See the module doc for the ownership rules.

The lock guards

type struct StdinLock {}

type struct StdoutLock {}

type struct StderrLock {}

lock() returns a guard that holds the stream's process-wide mutex until it drops, so a burst of writes from one thread is not interleaved with another's. The guards implement the same trait as the stream they lock, and release the mutex when dropped.

Trait implementations

Stdin

implement trait Read for struct Stdin

Stdout

implement trait Write for struct Stdout
implement trait FmtWrite for struct Stdout
std::fmt::write

Stderr

implement trait Write for struct Stderr
implement trait FmtWrite for struct Stderr
std::fmt::write

StdinLock

implement trait Read for struct StdinLock
implement trait Drop for struct StdinLock

StdoutLock

implement trait Write for struct StdoutLock
implement trait Drop for struct StdoutLock

StderrLock

implement trait Write for struct StderrLock
implement trait Drop for struct StderrLock

Free Functions

function stdin() -> Stdin;

Handle for process standard input.

function stdout() -> Stdout;

function stderr() -> Stderr;

function is_tty(fd: i32) -> boolean;

True if fd is a terminal. Used to choose line-buffered vs block-buffered output, to enable ANSI color, or to gate interactive prompts. libc::isatty returns nonzero for a terminal and 0 for everything else. Only zero means "not a TTY": msvcrt's _isatty answers 64 for a console, so a test against 1 reads every Windows terminal as redirected.

Constants

const STDIN_FD:      i32 = 0;
const STDOUT_FD:     i32 = 1;
const STDERR_FD:     i32 = 2;
const LINE_FEED:     u8  = 0x0A;
const NEWLINE_BYTES: u8* = "\n";
const NEWLINE:       Str = Str::new("\n");