lib/file.x

File I/O operations and stream handling.

Primary API

File

File.copy_to

int File.copy_to(File source, File output, size_t *copied)

Copies the remaining bytes from source to output. A null stream returns zero without raising; every other outcome returns nonzero or transfers. When copied is nonnull it receives the number of bytes written, including the partial count a catch observes after a failure.

Raises: <io-fail> on a source read or destination write failure.

Source: lib/file.x:465

File.getw

inline int File.getw(File file)

Reads and returns one native int, or EOF when a full word is unavailable. A stored value equal to EOF is indistinguishable from the sentinel without inspecting the stream indicators.

Source: lib/file.x:316

File.iter

Iter File.iter(File file, Iter dest)

Returns an iterator over File. The caller supplies dest; each pull yields one String under the canonical pool-chain lifetime described above, including its newline when present. The iterator borrows file, which must remain open through every pull. Clean EOF exhausts the iterator and releases its line storage. Abandoning it before exhaustion leaves that Scope-owned Block until its Scope is cleaned up. A null dest returns NULL; a null file initializes dest as exhausted.

Raises: <alloc-fail> while initializing. Pulling may raise the same causes as File.readline; none return to the pull, and a transfer releases the iterator’s line storage.

Source: lib/file.x:551

File.open

File File.open(const char *path, const char *mode)

Opens path with the requested stdio mode. The caller owns a successful stream and must close it. A missing path raises <not-found>; another host failure raises <io-fail>; and a null path or mode raises <bad-arg>. Host failures carry the path, operation, and captured errno.

Source: lib/file.x:260

File.read_into

FileReadStatus File.read_into(File file, Block dest)

Reads the remaining stream bytes into caller-owned storage. Valid inputs clear dest first. Null inputs or a Block width other than one report ERROR without raising and leave a nonnull dest unchanged; a read failure transfers instead, leaving its partial bytes in dest.

Raises: <io-fail> on a stream read error, or the cause reported by Block.append when the destination cannot grow.

Source: lib/file.x:434

File.readline_into

FileReadStatus File.readline_into(File file, Block dest)

Reads one raw line into caller-owned byte storage. Valid inputs clear dest, then include the newline when one is read. Null inputs or a Block width other than one report ERROR without raising and leave a nonnull dest unchanged; a read failure transfers instead, leaving its partial bytes in dest.

Raises: <io-fail> on a stream read error, or <size-limit> or <alloc-fail> when the destination cannot grow.

Source: lib/file.x:404

File.write_all

int File.write_all(File file, const void *ptr, size_t size)

Writes every requested byte unless the stream reports failure. A null stream or a null pointer with nonzero size returns zero without raising; every other outcome returns nonzero or transfers. A transfer may leave a prefix already written.

Raises: <io-fail> on a short or failed write, which does not return here.

Source: lib/file.x:452

String

String.open

File String.open(String fname, const char *mode)

Opens the filesystem path named by fname. The caller owns a successful stream and must close it. A missing path raises <not-found>; another host failure raises <io-fail>; and a null path or mode raises <bad-arg>. Host failures carry the path, operation, and captured errno.

Source: lib/file.x:234

Advanced and interop API

File

File.equal

int File.equal(File x, File y)

Reports whether x and y are the same native stream handle.

Source: lib/file.x:566

File.fdopen

File File.fdopen(int fildes, const char *mode)

Wraps an open file descriptor in a File stream. On success the returned stream owns fildes, which must be closed through the stream. On failure the caller still owns the descriptor. A host failure raises <io-fail> with the operation and captured errno; a null mode raises <bad-arg>.

Source: lib/file.x:243

File.gets

inline char *File.gets(File file, char *str, int size)

Reads a native line into str and returns str, or NULL at EOF or error. At most size - 1 bytes are stored followed by NUL, and a newline is kept when it fits.

Source: lib/file.x:297

File.hash

unsigned File.hash(File file)

Returns a handle-identity hash consistent with File.equal.

Source: lib/file.x:563

File.popen

File File.popen(const char *cmd, const char *mode)

Opens a process pipe with the requested mode. The caller owns a successful stream and must finish it with File.pclose to close the pipe and collect the child status. A host failure raises <not-found> for ENOENT or <io-fail> otherwise, with the command as path, operation, and captured errno; a null command or mode raises <bad-arg>.

Source: lib/file.x:270

File.printf

int File.printf(File file, const char *format, ...)

Formats values into file. Returns the character count or a negative value on failure.

Source: lib/file.x:355

File.putc

inline int File.putc(File file, int c)

Writes one byte and returns it as an unsigned char, or EOF on failure.

Source: lib/file.x:301

File.puts

inline int File.puts(File file, const char *s)

Writes a NUL-terminated C string. Returns a nonnegative value on success or EOF on failure.

Source: lib/file.x:306

File.putw

inline int File.putw(File file, int w)

Writes one native int and returns w, or EOF on a short write.

Source: lib/file.x:309

File.read

inline size_t File.read(File file, void *ptr, size_t size, size_t nitems)

Reads up to nitems elements and returns the number read.

Source: lib/file.x:332

File.reopen

Self File.reopen(Self file, const char *path, const char *mode)

Reuses file for a newly opened path and mode. This consumes the original stream even when the native reopen fails; after a transfer the caller must not close or reuse the old handle. A missing path raises <not-found>; another host failure raises <io-fail>; and a null stream, path, or mode raises <bad-arg>. Host failures carry the path, operation, and captured errno.

Source: lib/file.x:285

File.repr

String File.repr(File file)

Returns a readable handle and descriptor representation without reading.

Source: lib/file.x:569

File.scanf

int File.scanf(File file, const char *format, ...)

Scans values from file, returning the assignment count or EOF.

Source: lib/file.x:364

File.setbuffer

inline void File.setbuffer(File file, char *buf, int size)

Installs caller-supplied buffering, or disables buffering for a null buf. A nonnull buffer is borrowed until the stream closes or buffering changes.

Source: lib/file.x:343

File.setlinebuf

inline int File.setlinebuf(File file)

Requests line buffering for file and returns zero. The underlying setvbuf result is intentionally not exposed.

Source: lib/file.x:324

File.stat

inline int File.stat(File file, struct stat *buf)

Writes metadata for file into buf. Returns zero on success or -1 on a native error.

Source: lib/file.x:350

File.str

String File.str(File file)

Returns the display String for file. A nonnull file follows File.string. It advances through EOF, returns a canonical result under the pool-chain lifetime described above or NULL when empty, and transfers the same causes. A null handle returns its pointer representation without reading.

Source: lib/file.x:580

File.string

String File.string(File file)

Reads the remaining stream into one canonical String. Starts at the current position, advances through EOF, and returns NULL when no bytes remain.

Raises: <io-fail> on a stream read error, <bad-arg> when returned bytes contain an embedded NUL, <size-limit> when the String cannot be represented, or <alloc-fail> while constructing the result.

Source: lib/file.x:502

File.string_close

String File.string_close(File file)

Reads the remaining text, then closes file on return or transfer. The close result is discarded, so a close failure is not reported. The stream and all of its aliases are invalid afterward.

Raises: the same causes as File.string.

Source: lib/file.x:223

File.ungetc

inline int File.ungetc(File file, int c)

Pushes one byte back and returns it, or EOF when it cannot be pushed.

Source: lib/file.x:330

File.write

inline size_t File.write( File file, const void *ptr, size_t size, size_t nitems)

Writes up to nitems elements and returns the number written.

Source: lib/file.x:336

File.write_repr

Buffer File.write_repr(File file, Buffer out)

Appends the readable pointer representation of file to out.

Source: lib/file.x:583

Compatibility API

File

File.readblock

String File.readblock(File file, long size)

Reads up to size bytes into a canonical String. Reading starts at the current stream position and returns NULL when no bytes are read. This adapter is retained for source and ABI compatibility. For new code, prefer File.read_into.

Raises: <bad-arg> for a negative size, <size-limit> when the requested String cannot be represented, <bad-arg> when the bytes contain an embedded NUL, <io-fail> on a stream read error, or <alloc-fail> while constructing the result.

Source: lib/file.x:382

File.readline

String File.readline(File file)

Reads one raw line into a canonical String. Includes the newline when present. Clean EOF and FILE_READ_ERROR both map to NULL; use the status-bearing forms when that distinction matters. This adapter is retained for source and ABI compatibility. For new code, prefer File.readline_into or File.iter when raw status and bytes should remain separate.

Raises: <io-fail> on a stream read error, <bad-arg> when returned bytes are not valid String text, <size-limit> when the line cannot be represented, or <alloc-fail> while constructing the result.

Source: lib/file.x:485

Runtime-internal callables

These callables connect runtime translation units. They are documented for source readers but are not supported as user API.

File

File.initialize

void File.initialize(void)

Publishes the process’s borrowed standard streams as File globals. The globals do not take ownership or arrange cleanup of the native streams.

Source: lib/file.x:591

Public types

File

typedef FILE *File

Names a native stdio stream handle. A successful open returns an owned stream. Stdin, Stdout, and Stderr are borrowed. An alias does not retain a stream, and closing one invalidates every alias.

Source: lib/file.x:28

FileReadStatus

typedef enum FileReadStatus { FILE_READ_ERROR = -1, FILE_READ_EOF = 0, FILE_READ_DATA = 1 } FileReadStatus

Reports whether a raw File read produced bytes, reached clean EOF, or rejected its arguments. Host read failures transfer <io-fail> instead of returning FILE_READ_ERROR.

Source: lib/file.x:63

Design notes

Wraps native FILE streams while preserving stream-handle identity for hash, equality, and ordering. Raw read and copy operations report status separately from bytes written. String adapters canonicalize through the active pool chain. A returned identity may already belong to an ancestor and lives until its actual owning pool is released; NULL is the empty String. Other return values, stream position, buffering, and error indicators follow stdio unless an operation documents different status behavior. Stdin, Stdout, and Stderr are initialized as borrowed process streams.

Tests and examples

make verify (unittest/test-file.x) and make examples (docs-word-count).