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");grantpt() → {boolean}nullable
Grants access to a pseudo-terminal slave device.
Allows the owner of the pseudo-terminal master device to grant the appropriate permissions on the corresponding slave device so that it may be opened.
This function is typically called before opening the slave device.
Returns true on success.
Returns null if an error occurred.
const master = io.open('/dev/ptmx', O_RDWR);
if (master.grantpt()) {
print("Granted access to slave device\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");ptsname() → {string}nullable
Gets the name of the pseudo-terminal slave.
Returns the name of the pseudo-terminal slave device associated with the master file descriptor.
Returns a string containing the slave device name.
Returns null if an error occurred or if the descriptor is not a pseudo-terminal master.
const master = io.open('/dev/ptmx', O_RDWR);
const slave_name = master.ptsname();
print(slave_name, "\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 starttcgetattr() → {object}nullable
Gets terminal attributes.
Retrieves the terminal attributes for the file descriptor.
Returns an object containing terminal attributes (iflag, oflag, cflag, lflag, ispeed, ospeed, and cc array).
Returns null if an error occurred or if the descriptor is not a terminal.
const handle = io.open('/dev/tty', O_RDWR);
const attrs = handle.tcgetattr();
if (attrs)
print("Input flags: ", attrs.iflag, "\n");tcsetattr(attrs, whenopt) → {boolean}nullable
Sets terminal attributes.
Sets the terminal attributes for the file descriptor.
The attrs parameter should be an object with properties:
- iflag: input flags
- oflag: output flags
- cflag: control flags
- lflag: local flags
- ispeed: input speed
- ospeed: output speed
- cc: array of control characters (optional)
Returns true on success.
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
attrs | object | The terminal attributes to set. |
when | number | (optional, default: 0)When to apply the changes (TCSANOW, TCSADRAIN, TCSAFLUSH). |
const handle = io.open('/dev/tty', O_RDWR);
const attrs = handle.tcgetattr();
attrs.lflag &= ~0x0000008; // Disable ECHO
handle.tcsetattr(attrs, TCSANOW);tell() → {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();unlockpt() → {boolean}nullable
Unlocks a pseudo-terminal slave device.
Unlocks the pseudo-terminal slave device associated with the master device referred to by the file descriptor. This function is typically called after grantpt() and before opening the slave device.
Returns true on success.
Returns null if an error occurred.
const master = io.open('/dev/ptmx', O_RDWR);
master.grantpt();
if (master.unlockpt()) {
print("Unlocked slave device\n");
}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');