std / io/stream

io/stream

import "std:io/stream"

Provides OS-dependent stream I/O operations wrapping C FILE* handles. Open files, read and write bytes and strings, seek within streams, and adapt streams to io.Reader/io.Writer interfaces. For pure reader/writer abstractions, use the "std:io" package instead.

View source on Codeberg →

Index

Types Seek Constants Open Mode Flags Stdin Stdout Stderr Open Close ReadByte ReadBytes ReadString WriteByte WriteBytes WriteString Flush Seek Tell IsEOF HasError ClearError ToReader ToWriter ToCloser ToReadWriter ToReadCloser ToWriteCloser ToReadWriteCloser

Types

# 
type File struct {}

Opaque type representing a C FILE* handle.

# 
type Stream struct {
    handle *File
}

Stream wraps a C FILE* for I/O operations.

Seek Constants

# 
const (
    SEEK_SET = iota  /* Seek from beginning of file */
    SEEK_CUR          /* Seek from current position */
    SEEK_END          /* Seek from end of file */
)

Seek mode constants for use with Seek.

Open Mode Flags

# 
const (
    O_READ   = 1 << iota  /* Open for reading */
    O_WRITE                /* Open for writing */
    O_APPEND               /* Append mode */
    O_CREATE               /* Create if doesn't exist */
    O_TRUNC                /* Truncate existing file */
    O_BINARY               /* Binary mode (no text translation) */
)

Open mode flags, OR'ed together and passed to Open.

Standard Streams

# 
func Stdin() Stream

Returns a Stream wrapping standard input.

# 
func Stdout() Stream

Returns a Stream wrapping standard output.

# 
func Stderr() Stream

Returns a Stream wrapping standard error.

Stream Lifecycle

# 
func Open(path string, mode int) (Stream, io.Error)

Opens a file with the specified mode flags. Mode flags are OR'ed together: O_READ, O_WRITE, O_APPEND, O_CREATE, O_TRUNC, O_BINARY. Returns (Stream, OK) on success, (Stream{}, ErrIO) on failure.

# 
func Close(s Stream) io.Error

Closes the stream. Returns OK on success, ErrIO on failure, ErrClosed if already closed.

Read Operations

# 
func ReadByte(s Stream) (byte, io.Error)

Reads a single byte from the stream. Returns (byte, OK) on success, (0, EOF) on end-of-file, (0, ErrIO) on error.

# 
func ReadBytes(s Stream, buf []byte) (int, io.Error)

Reads up to len(buf) bytes from the stream into buf. Returns (n, OK) where n is bytes read, (n, EOF) if EOF reached, (0, ErrIO) on error.

# 
func ReadString(s Stream) (string, io.Error)

Reads a line from the stream (up to newline or EOF). Returns (string, OK) on success, ("", EOF) on end-of-file, ("", ErrIO) on error. The returned string includes the newline if present.

Write Operations

# 
func WriteByte(s Stream, b byte) io.Error

Writes a single byte to the stream. Returns OK on success, ErrIO on failure.

# 
func WriteBytes(s Stream, buf []byte) (int, io.Error)

Writes bytes to the stream. Returns (n, OK) where n is bytes written, (n, ErrIO) on partial write or error.

# 
func WriteString(s Stream, str string) (int, io.Error)

Writes a string to the stream. Returns (n, OK) where n is bytes written, (n, ErrIO) on partial write or error.

Control Operations

# 
func Flush(s Stream) io.Error

Flushes any buffered data to the underlying storage. Returns OK on success, ErrIO on failure.

# 
func Seek(s Stream, offset, whence int) io.Error

Sets the stream position. whence: SEEK_SET (0), SEEK_CUR (1), or SEEK_END (2). Returns OK on success, ErrIO on failure.

# 
func Tell(s Stream) (int, io.Error)

Returns the current stream position. Returns (position, OK) on success, (-1, ErrIO) on failure.

# 
func IsEOF(s Stream) bool

Returns true if the stream is at end-of-file.

# 
func HasError(s Stream) bool

Returns true if the stream has an error condition.

# 
func ClearError(s Stream)

Clears the error and EOF indicators on the stream.

Interface Adapters

# 
func ToReader(s *Stream) io.Reader

Creates an io.Reader for a Stream.

# 
func ToWriter(s *Stream) io.Writer

Creates an io.Writer for a Stream.

# 
func ToCloser(s *Stream) io.Closer

Creates an io.Closer for a Stream.

# 
func ToReadWriter(s *Stream) io.ReadWriter

Creates an io.ReadWriter for a Stream.

# 
func ToReadCloser(s *Stream) io.ReadCloser

Creates an io.ReadCloser for a Stream.

# 
func ToWriteCloser(s *Stream) io.WriteCloser

Creates an io.WriteCloser for a Stream.

# 
func ToReadWriteCloser(s *Stream) io.ReadWriteCloser

Creates an io.ReadWriteCloser for a Stream.