Lua IO Library (files/stdio)

io

Lua 5.1's io library for byte-level reading and writing of local files and the standard streams. Prefer linkiir.sys.fs for file management and linkiir.link.file for remote files.

---

io.open

function

io.open(filename [, mode])

Open a file.

Opens a file in the given mode ("r" by default) and returns a file handle, or nil and an error message. A relative path resolves against linkiir.sys.workingDir(), and a path escaping it with .. raises an error.

Usage

local f, err = io.open(filename, mode)

Parameters

Name	Type	Required	Description
filename	string	Yes	Path to open.
mode	string	No	r/w/a, optionally with b and/or +. Default "r".

Returns

• file handle on success; nil, errorMessage on failure

Example

local F, Err = io.open(linkiir.sys.nodeDir() .. '/scratch.txt', 'w')
if not F then error(Err) end
F:write('hello')
F:close()

io.close

function

io.close([file])

Close a file.

Closes file (default the current default output file). Equivalent to file:close().

Usage

io.close(file)

Parameters

Name	Type	Required	Description
file	file	No	File handle to close. Default the current output file.

Returns

• true on success; nil, errorMessage on failure

Example

local F = io.open('/tmp/x.txt', 'r')
-- ... use F ...
io.close(F)

io.read

function

io.read(...)

Read from the default input file.

Reads from the current default input file, using the same formats as file:read.

Usage

io.read(format)

Parameters

Name	Type	Required	Description
...	string	No	Format specifiers ("*l", "*n", "*a", or a byte count). Default "*l".

Returns

• the values read, per format; nil at end of file

Example

local Line = io.read('*l')

io.write

function

io.write(...)

Write to the default output file.

Writes the given strings/numbers to the current default output file, using the same rules as file:write.

Usage

io.write(...)

Parameters

Name	Type	Required	Description
...	string|number	Yes	Values to write (variadic).

Returns

• the default output file, for chaining; nil, errorMessage on failure

Example

io.write('processed ', tostring(Count), ' records\n')

io.lines

function

io.lines([filename, ...])

Iterate the lines of a file.

Returns an iterator over the lines of a file, closing it at the end. A relative path resolves against linkiir.sys.workingDir(), and a path escaping it with .. raises an error.

Usage

for line in io.lines(filename) do ... end

Parameters

Name	Type	Required	Description
filename	string	No	Path to read. Default the current input file.
...	string	No	Read formats (as in file:read). Default "*l".

Returns

• iterator function, for use in a generic for loop

Example

for Line in io.lines(linkiir.sys.nodeDir() .. '/data.csv') do
   print(Line)
end

io.input

function

io.input([file])

Get/set the default input file.

Sets the default input file from a file name or handle, or returns it. A relative path resolves against linkiir.sys.workingDir(), and a path escaping it with .. raises an error.

Usage

io.input(file)

Parameters

Name	Type	Required	Description
file	string|file	No	Filename to open, or an already-open file handle.

Returns

• the default input file

Example

io.input(linkiir.sys.nodeDir() .. '/data.csv')
local Line = io.read('*l')

io.output

function

io.output([file])

Get/set the default output file.

Sets the default output file from a file name or handle, or returns it. A relative path resolves against linkiir.sys.workingDir(), and a path escaping it with .. raises an error.

Usage

io.output(file)

Parameters

Name	Type	Required	Description
file	string|file	No	Filename to open, or an already-open file handle.

Returns

• the default output file

Example

io.output('/tmp/out.txt')
io.write('done\n')

io.popen

function

io.popen(prog [, mode])

Run a shell command, connected via a pipe.

Runs a shell command and returns a file handle to read its output or write its input. Avoid it in workflow scripts; use linkiir.link.file or linkiir.link.web instead.

Usage

local f = io.popen(prog, mode)

Parameters

Name	Type	Required	Description
prog	string	Yes	Shell command line to run.
mode	string	No	"r" (read prog's stdout) or "w" (write to prog's stdin). Default "r".

Returns

• file handle on success; nil, errorMessage on failure

Example

-- Avoid in Linkiir scripts; shown for reference only.
local P = io.popen('date', 'r')
print(P:read('*l'))
P:close()

io.tmpfile

function

io.tmpfile()

Open a temporary file.

Returns a handle for a temporary file, opened in update mode ('w+'), that is automatically removed when the script ends.

Usage

io.tmpfile()

Returns

• file handle on success; nil, errorMessage on failure

Example

local F = io.tmpfile()
F:write('scratch')
F:seek('set', 0)
print(F:read('*a'))

io.type

function

io.type(obj)

Test whether a value is a file handle.

Returns "file" if obj is an open file handle, "closed file" if it is a closed file handle, or nil if it is not a file handle at all.

Usage

io.type(obj)

Parameters

Name	Type	Required	Description
obj	any	Yes	Value to test.

Returns

• "file", "closed file", or nil

Example

local F = io.open('/tmp/x.txt', 'r')
print(io.type(F))  -- "file"
F:close()
print(io.type(F))  -- "closed file"

io.stdin

field

io.stdin

The process's standard input file handle.

The process's standard input, as a file handle.

Usage

io.stdin

Returns

• file handle

Example

local Line = io.stdin:read('*l')

io.stdout

field

io.stdout

The process's standard output file handle.

The process's standard output, as a file handle.

Usage

io.stdout

Returns

• file handle

Example

io.stdout:write('hello\n')

io.stderr

field

io.stderr

The process's standard error file handle.

The process's standard error, as a file handle.

Usage

io.stderr

Returns

• file handle

Example

io.stderr:write('warning: retrying\n')

File methods

File:read

method of File

file:read(...)

Read from a file.

Reads from file per the given format(s): "*l" a line without the newline (default), "*L" a line with the newline, "*a" the whole rest of the file, "*n" a number, or an integer n for up to n bytes. Returns nil (or an empty string for "*a") at end of file.

Usage

local Line = f:read('*l')

Parameters

Name	Type	Required	Description
...	string|integer	No	One or more read formats. Default "*l".

Returns

• the value(s) read, one per format; nil at end of file

Example

local F = io.open(Path, 'r')
local All = F:read('*a')
F:close()

File:write

method of File

file:write(...)

Write to a file.

Writes the given strings/numbers to file. Numbers are converted per their usual string representation.

Usage

f:write('hello')

Parameters

Name	Type	Required	Description
...	string|number	Yes	Values to write (variadic).

Returns

• file, for chaining; nil, errorMessage on failure

Example

local F = io.open(Path, 'w')
F:write('id,name\n')
F:write('1,Alice\n')
F:close()

File:close

method of File

file:close()

Close a file.

Closes file. Files are also closed automatically (in an unspecified order) when their handle is garbage-collected, but explicit close is recommended.

Usage

f:close()

Returns

• true on success; nil, errorMessage on failure

Example

local F = io.open(Path, 'r')
-- ... use F ...
F:close()

File:lines

method of File

file:lines(...)

Iterate the lines of an already-open file.

Returns an iterator function that, each time it is called, reads the next line from file per the given format(s) (as file:read; default "*l"). Does not close file when done.

Usage

for line in f:lines() do ... end

Parameters

Name	Type	Required	Description
...	string	No	Read formats. Default "*l".

Returns

• iterator function, for use in a generic for loop

Example

local F = io.open(Path, 'r')
for Line in F:lines() do
   print(Line)
end
F:close()

File:seek

method of File

file:seek([whence [, offset]])

Get/set the file position.

Gets or sets the file position, from "set" (start), "cur" (current, the default) or "end". With no arguments, returns the current position.

Usage

local pos = f:seek('set', 0)

Parameters

Name	Type	Required	Description
whence	string	No	"set", "cur", or "end". Default "cur".
offset	integer	No	Byte offset from whence. Default 0.

Returns

• the new file position (bytes from the start); nil, errorMessage on failure

Example

local F = io.open(Path, 'r')
local Size = F:seek('end')
F:seek('set', 0)
F:close()

File:flush

method of File

file:flush()

Flush buffered writes.

Saves any written data to file, without closing it.

Usage

f:flush()

Returns

• file, for chaining

Example

F:write('partial')
F:flush()

File:setvbuf

method of File

file:setvbuf(mode [, size])

Set the file's buffering mode.

Sets the buffering mode for an output file: "no" (unbuffered), "full" (buffer up to size bytes, flushed when full or explicitly), or "line" (line-buffered).

Usage

f:setvbuf('line')

Parameters

Name	Type	Required	Description
mode	string	Yes	"no", "full", or "line".
size	integer	No	Buffer size in bytes (for "full").

Returns

• true on success

Example

F:setvbuf('line')