Represents a handle for interacting with a file descriptor.
const handle = io.open(…);
handle.read(…);
handle.write(…);
handle.seek(…);
handle.tell();
handle.fileno();
handle.close();
handle.error();Methods
close() → {boolean}nullable
Closes the file descriptor.
Closes the underlying file descriptor. Further operations on this handle will fail.
Returns true if the descriptor was successfully closed.
Returns null if an error occurred.
const handle = io.open('/tmp/test.txt', O_RDONLY);
handle.close();dup() → {handle}nullable
Duplicates the file descriptor.
Creates a duplicate of the file descriptor using dup(2).
Returns a new io.handle for the duplicated descriptor.
Returns null if an error occurred.
const handle = io.open('/tmp/test.txt', O_RDONLY);
const dup_handle = handle.dup();dup2(newfd) → {boolean}nullable
Duplicates the file descriptor to a specific descriptor number.
Creates a duplicate of the file descriptor to the specified descriptor number using dup2(2). If newfd was previously open, it is silently closed.
Returns true on success.
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
newfd | number | The target file descriptor number. |
const handle = io.open('/tmp/test.txt', O_WRONLY);
handle.dup2(2); // Redirect stderr to the fileerror() → {string}nullable
Query error information.
Returns a string containing a description of the last occurred error or null if there is no error information.
// Trigger an error
io.open('/path/does/not/exist');
// Print error (should yield "No such file or directory")
print(io.error(), "\n");fcntl(cmd, argopt) → {number|handle}nullable
Performs fcntl() operations on the file descriptor.
Performs the specified fcntl() command on the file descriptor with an optional argument.
Returns the result of the fcntl() call. For F_DUPFD and F_DUPFD_CLOEXEC, returns a new io.handle wrapping the duplicated descriptor. For other commands, returns a number (interpretation depends on cmd).
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
cmd | number | The fcntl command (e.g., F_GETFL, F_SETFL, F_GETFD, F_SETFD, F_DUPFD). |
arg | number | (optional) Optional argument for the command. |
const handle = io.open('/tmp/test.txt', O_RDONLY);
const flags = handle.fcntl(F_GETFL);
handle.fcntl(F_SETFL, flags | O_NONBLOCK);
const dup_handle = handle.fcntl(F_DUPFD, 10); // Returns io.handlefileno() → {number}nullable
Gets the file descriptor number.
Returns the underlying file descriptor number.
Returns null if the handle is closed.
const handle = io.open('/tmp/test.txt', O_RDONLY);
print(handle.fileno(), "\n");ioctl(direction, type, num, valueopt) → {number|string}
Performs an ioctl operation on the file descriptor.
The direction parameter specifies who is reading and writing, from the user's point of view. It can be one of the following values:
| Direction | Description |
|---|---|
| IOC_DIR_NONE | neither userspace nor kernel is writing, ioctl is executed without passing data. |
| IOC_DIR_WRITE | userspace is writing and kernel is reading. |
| IOC_DIR_READ | kernel is writing and userspace is reading. |
| IOC_DIR_RW | userspace is writing and kernel is writing back into the data structure. |
Returns the result of the ioctl operation; for IOC_DIR_READ and IOC_DIR_RW this is a string containing the data, otherwise a number as return code.
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
direction | number | The direction of the ioctl operation. Use constants IOC_DIR_*. |
type | number | The ioctl type (see https://www.kernel.org/doc/html/latest/userspace-api/ioctl/ioctl-number.html) |
num | number | The ioctl sequence number. |
value | number | | (optional) The value to pass to the ioctl system call. For |
const handle = io.open('/dev/tty', O_RDWR);
const size = handle.ioctl(IOC_DIR_READ, 0x54, 0x13, 8); // TIOCGWINSZisatty() → {boolean}nullable
Checks if the file descriptor refers to a terminal.
Returns true if the descriptor refers to a terminal device.
Returns false otherwise.
Returns null if an error occurred.
const handle = io.new(0); // stdin
if (handle.isatty())
print("Running in a terminal\n");read(length) → {string}nullable
Reads data from the file descriptor.
Reads up to the specified number of bytes from the file descriptor.
Returns a string containing the read data.
Returns an empty string on EOF.
Returns null if a read error occurred.
| Name | Type | Description |
|---|---|---|
length | number | The maximum number of bytes to read. |
const handle = io.open('/tmp/test.txt', O_RDONLY);
const data = handle.read(1024);seek(offsetopt, whenceopt) → {boolean}nullable
Sets the file descriptor position.
Sets the file position of the descriptor to the given offset and whence.
Returns true if the position was successfully set.
Returns null if an error occurred.
| Name | Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
offset | number | (optional, default: 0)The offset in bytes. | ||||||||
whence | number | (optional, default: 0)The position reference.
|
const handle = io.open('/tmp/test.txt', O_RDONLY);
handle.seek(100, 0); // Seek to byte 100 from starttell() → {number}nullable
Gets the current file descriptor position.
Returns the current file position as an integer.
Returns null if an error occurred.
const handle = io.open('/tmp/test.txt', O_RDONLY);
const pos = handle.tell();write(data) → {number}nullable
Writes data to the file descriptor.
Writes the given data to the file descriptor. Non-string values are converted to strings before being written.
Returns the number of bytes written.
Returns null if a write error occurred.
| Name | Type | Description |
|---|---|---|
data | * | The data to write. |
const handle = io.open('/tmp/test.txt', O_WRONLY | O_CREAT);
handle.write('Hello World\n');