Represents a handle for interacting with a file opened by one of the file open functions.
const handle = open(…);
handle.read(…);
handle.write(…);
handle.flush();
handle.seek(…);
handle.tell();
handle.isatty();
handle.fileno();
handle.close();
handle.error();Methods
close() → {boolean}nullable
Closes the file handle.
Upon calling close() on the handle, buffered data is flushed and the underlying file descriptor is closed.
Returns true if the handle was properly closed.
Returns null if an error occurred.
error() → {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 file system error
unlink('/path/does/not/exist');
// Print error (should yield "No such file or directory")
print(error(), "\n");fileno() → {number}nullable
Obtains the number of the handle's underlying file descriptor.
Returns the descriptor number.
Returns null on error.
flush() → {boolean}nullable
Forces a write of all buffered data to the underlying handle.
Returns true if the data was successfully flushed.
Returns null on error.
ioctl(direction, type, num, size, payloadnullable) → {number|string}
Performs an ioctl operation on the file.
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 |
|---|---|
| 0 | NONE - neither userspace nor kernel is writing, ioctl is executed without passing data. |
| 1 | WRITE - userspace is writing and kernel is reading. |
| 2 | READ - kernel is writing and userspace is reading. |
| 3 | READ+WRITE - userspace is writing and kernel is writing back into the data structure. |
The size parameter has a different purpose depending on the direction parameter:
- direction = 0 -> the size parameter is not used
- direction = 1 -> size must be the length (in bytes) of argp
- direction = 2 -> expected length (in bytes) of the data returned by kernel
- direction = 3 -> size is the length (in bytes) of argp, and the length of the data returned by kernel.
The argp parameter should be the data to be written for direction '1' and '3', otherwise null.
Returns the result of the ioctl operation; for direction '2' and '3' this is a string containing the data, otherwise a number as return code. In case of an error, null is returned and the error code is available via last_error.
| Name | Type | Description |
|---|---|---|
direction | number | The direction of the ioctl operation. |
type | number | ioctl type (see https://www.kernel.org/doc/html/latest/userspace-api/ioctl/ioctl-number.html) |
num | number | ioctl sequence number. |
size | number | The size of the ioctl operation payload. |
payload | string | (nullable) The ioctl payload. |
isatty() → {boolean}nullable
Check for TTY.
Checks whether the open file handle refers to a TTY (terminal) device.
Returns true if the handle refers to a terminal.
Returns false if the handle refers to another kind of file.
Returns null on error.
lock(opopt) → {boolean}nullable
Locks or unlocks a file.
The mode argument specifies lock/unlock operation flags.
| Flag | Description |
|---|---|
| "s" | shared lock |
| "x" | exclusive lock |
| "n" | don't block when locking |
| "u" | unlock |
Returns true if the file was successfully locked/unlocked.
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
op | string | (optional) The lock operation flags |
read(length) → {string}nullable
Reads a chunk of data from the file handle.
The length argument may be either a positive number of bytes to read, in which case the read call returns up to that many bytes, or a string to specify a dynamic read size.
If length is a number, the method will read the specified number of bytes from the handle. Reading stops after the given amount of bytes or after encountering EOF, whatever comes first.
If length is the string "line", the method will read an entire line, terminated by "\n" (a newline), from the handle. Reading stops at the next newline or when encountering EOF. The returned data will contain the terminating newline character if one was read.
If length is the string "all", the method will read from the handle until encountering EOF and return the complete contents.
If length is a single character string, the method will read from the handle until encountering the specified character or upon encountering EOF. The returned data will contain the terminating character if one was read.
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 length of data to read. Can be a number, the string "line", the string "all", or a single character string. |
const fp = open("file.txt", "r");
// Example 1: Read 10 bytes from the handle
const chunk = fp.read(10);
// Example 2: Read the handle line by line
for (let line = fp.read("line"); length(line); line = fp.read("line"))
print(line);
// Example 3: Read the complete contents from the handle
const content = fp.read("all");
// Example 4: Read until encountering the character ':'
const field = fp.read(":");seek(offsetopt, positionopt) → {boolean}nullable
Set file read position.
Set the read position of the open file handle to the given offset and position.
Returns true if the read position was set.
Returns null if an error occurred.
| Name | Type | Description | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|
offset | number | (optional, default: 0)The offset in bytes. | ||||||||
position | number | (optional, default: 0)The position of the offset.
|
const fp = open("file.txt", "r");
print(fp.read(100), "\n"); // read 100 bytes...
fp.seek(0, 0); // ... and reset position to start of file
print(fp.read(100), "\n"); // ... read same 100 bytes again
fp.seek(10, 1); // skip 10 bytes forward, relative to current offset ...
fp.tell(); // ... position is at 110 now
fp.seek(-10, 2); // set position to ten bytes before EOF ...
print(fp.read(100), "\n"); // ... reads 10 bytes at mosttell() → {number}nullable
Obtain current read position.
Obtains the current, absolute read position of the open file.
Returns an integer containing the current read offset in bytes.
Returns null if an error occurred.
truncate(offsetopt) → {boolean}nullable
Truncate file to a given size
Returns true if the file was successfully truncated.
Returns null if an error occurred.
| Name | Type | Description |
|---|---|---|
offset | number | (optional, default: 0)The offset in bytes. |
write(data) → {number}nullable
Writes a chunk of data to the file handle.
In case the given data is not a string, it is converted to a string before being written into the file. String values are written as-is, integer and double values are written in decimal notation, boolean values are written as true or false while arrays and objects are converted to their JSON representation before being written. The null value is represented by an empty string so file.write(null) would be a no-op. Resource values are written in the form <type address>, e.g. <fs.file 0x7f60f0981760>.
If resource, array or object values contain a tostring() function in their prototypes, then this function is invoked to obtain an alternative string representation of the value.
Returns the number of bytes written.
Returns null if a write error occurred.
| Name | Type | Description |
|---|---|---|
data | * | The data to be written. |
const fp = open("file.txt", "w");
fp.write("Hello world!\n");