lib/file.x

File I/O operations and stream handling.

Primary API

File

File.cleanup

void File.cleanup(File value)

Ends the owned lifetime when a managed local leaves its block.

Source: lib/file.x:67

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:313

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:406

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:354

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:528

File.path_error

void File.path_error(Var operation, String path, int error)

Raises <not-found> when error is ENOENT and <io-fail> otherwise, with operation, path, and errno details.

Source: lib/file.x:496

File.read_into

FileReadStatus File.read_into(File f, Block dest)

Reads the remaining stream bytes into caller-owned storage. Valid inputs clear dest first. Returns <data> when bytes were read or <eof> at clean EOF. 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:273

File.readline_into

FileReadStatus File.readline_into(File f, Block dest)

Reads one raw line into caller-owned byte storage. Valid inputs clear dest, then include the newline when one is read. Returns <data> when bytes were read or <eof> at clean EOF. 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:243

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:300

String

String.open

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

Opens the filesystem path named by s. 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:520

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:469

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:537

File.gets

inline char *File.gets(File f, 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:388

File.hash

unsigned File.hash(File file)

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

Source: lib/file.x:466

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:552

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:446

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:391

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:396

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:399

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:423

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:567

File.repr

String File.repr(File file)

Returns a readable handle and descriptor representation without reading.

Source: lib/file.x:472

File.scanf

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

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

Source: lib/file.x:455

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:434

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:414

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:441

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:483

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:93

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:147

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:420

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:427

File.write_repr

Buffer File.write_repr(File file, Buffer out)

Appends the readable pointer representation of file to out.

Source: lib/file.x:486

Convenience 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. Prefer File.read_into for raw bytes and explicit status.

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:130

File.readline

String File.readline(File file)

Reads one raw line into a canonical String. Includes the newline when present. Clean EOF and <error> both map to NULL. 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:115

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:586

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:30

FileReadStatus

typedef Symbol FileReadStatus

Reports <data> when a raw File read produced bytes, <eof> at clean EOF, or <error> for invalid arguments. Host read failures transfer <io-fail> instead of returning <error>.

Source: lib/file.x:65

Design notes

A File is a native stdio stream whose handle identity serves hashing, equality, and ordering. Raw reads and copies report status separately from the bytes they move. Other results, stream position, buffering, and error indicators follow stdio unless an operation documents otherwise. The standard streams are borrowed from the process.

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.

Tests and examples

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