Expand description
Standard I/O library — io.* functions and file:* methods.
C source: reference/lua-5.4.7/src/liolib.c.
Impurity is host-provided and load-bearing. Filesystem and process
access reach the host only through hooks: regular files via
GlobalState::file_open_hook, io.popen via GlobalState::popen_hook,
stdout/stderr via output hooks. The native CLI installs hooks backed by
std::fs/std::process/std::io; sandboxed and wasm32 hosts leave those
capabilities absent, and the functions then return a clean (nil, msg, errno) failure tuple (or, for the standard streams, an Unsupported error)
instead of touching ambient OS state. That hook plumbing and the wasm32
cfg gates are deliberately kept intact.
The side-table indirection is the one structural divergence from C: C
stores the LStream inside the userdata payload, but LStream carries heap
pointers (a Box<dyn LuaFileHandle> and a fn pointer) that cannot be safely
reinterpreted from a raw byte buffer in safe Rust, so the stream lives in a
thread-local LSTREAM_REGISTRY keyed by userdata identity. Each I/O step
borrows the file through its Rc<RefCell<LStream>> briefly, releases the
borrow, then touches LuaState — resolving C’s single LStream * aliasing
into two scoped borrows.
Graduation: the deterministic format-parsing/validation and error-shaping
surface (read formats, the *-prefix version seam, the closed-file error,
io.type) is pinned by tests/io_strengthen.rs against the reference
binaries; host-specific I/O results are not reproducible and stay
oracle-checked only through the official files.lua suite. See
crates/lua-stdlib/GRADUATED.md.
Structs§
- LStream
- A Lua file handle. C equivalent:
typedef luaL_Stream LStream.
Enums§
- BufMode
- Buffering mode for
file:setvbuf. C:{_IONBF, _IOFBF, _IOLBF}. - Seek
Whence - Seek anchor for
file:seek. C:{SEEK_SET, SEEK_CUR, SEEK_END}. - StdFile
Kind - Which standard stream to wrap in
create_std_file.
Constants§
- FILE_
METAMETHODS - File-handle metamethods. C:
static const luaL_Reg metameth[]. - FILE_
METHODS file:*instance methods. C:static const luaL_Reg meth[].- IO_LIB
io.*module functions. C:static const luaL_Reg iolib[].- LUA_
FILE_ HANDLE - Name of the file-handle metatable in the Lua registry. C:
LUA_FILEHANDLE.
Traits§
- LuaFile
Ops - Capabilities required by the io library from an OS file handle.
Functions§
- f_flush
file:flush(). C:f_flush.- f_lines
file:lines(...). C:f_lines.- f_read
file:read(...). C:f_read.- f_seek
file:seek([whence [, offset]]). C:f_seek.- f_
setvbuf file:setvbuf(mode [, size]). C:f_setvbuf.- f_write
file:write(...). C:f_write→g_write(L, tofile(L), 2).- io_
close io.close([file]). C:io_close.- io_
flush io.flush(). C:io_flush.- io_
input io.input([file]). C:io_input.- io_
lines io.lines([filename, ...]). C:io_lines.- io_open
io.open(filename [, mode]). C:io_open.- io_
output io.output([file]). C:io_output.- io_
popen io.popen(filename [, mode]). C:io_popen.- io_read
io.read(...). C:io_read.- io_
tmpfile io.tmpfile(). C:io_tmpfile.- io_type
io.type(x)— return"file","closed file", or the fail value for a non-handle. C:io_type.- io_
write io.write(...). C:io_write→g_write(L, getiofile(IO_OUTPUT), 1).- luaopen_
io - Open the
iolibrary and return 1 (the library table). C:luaopen_io.