fs. file

Represents a handle for interacting with a file opened by one of the file open functions.

Example
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.

Returns: boolean

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.

Returns: string
Example
// 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.

Returns: number

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.

Returns: boolean

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:

DirectionDescription
0NONE - neither userspace nor kernel is writing, ioctl is executed without passing data.
1WRITE - userspace is writing and kernel is reading.
2READ - kernel is writing and userspace is reading.
3READ+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.

Parameters:
NameTypeDescription
directionnumber

The direction of the ioctl operation.

typenumber

ioctl type (see https://www.kernel.org/doc/html/latest/userspace-api/ioctl/ioctl-number.html)

numnumber

ioctl sequence number.

sizenumber

The size of the ioctl operation payload.

payloadstring(nullable)

The ioctl payload.

Returns: number | string

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.

Returns: boolean

lock(opopt) → {boolean}nullable

Locks or unlocks a file.

The mode argument specifies lock/unlock operation flags.

FlagDescription
"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.

Parameters:
NameTypeDescription
opstring(optional)

The lock operation flags

Returns: boolean

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.

Parameters:
NameTypeDescription
lengthnumber | string

The length of data to read. Can be a number, the string "line", the string "all", or a single character string.

Returns: string
Example
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.

Parameters:
NameTypeDescription
offsetnumber(optional, default: 0)

The offset in bytes.

positionnumber(optional, default: 0)

The position of the offset.

PositionDescription
0The given offset is relative to the start of the file. This is the default value if omitted.
1The given offset is relative to the current read position.
2The given offset is relative to the end of the file.
Returns: boolean
Example
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 most

tell() → {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.

Returns: number

truncate(offsetopt) → {boolean}nullable

Truncate file to a given size

Returns true if the file was successfully truncated.

Returns null if an error occurred.

Parameters:
NameTypeDescription
offsetnumber(optional, default: 0)

The offset in bytes.

Returns: boolean

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.

Parameters:
NameTypeDescription
data*

The data to be written.

Returns: number
Example
const fp = open("file.txt", "w");

fp.write("Hello world!\n");