Represents a handle for interacting with a program launched by popen().
const handle = popen(…);
handle.read(…);
handle.write(…);
handle.flush();
handle.fileno();
handle.close();
handle.error();- See
Methods
close() → {number}nullable
Closes the program handle and awaits program termination.
Upon calling close() on the handle, the program's input or output stream (depending on the open mode) is closed. Afterwards, the function awaits the termination of the underlying program and returns its exit code.
When the program was terminated by a signal, the return value will be the negative signal number, e.g.
-9for SIGKILL.When the program terminated normally, the return value will be the positive exit code of the program.
Returns a negative signal number if the program was terminated by a signal.
Returns a positive exit code if the program terminated normally.
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.
read(length) → {string}nullable
Reads a chunk of data from the program 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 = popen("command", "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(":");write(data) → {number}nullable
Writes a chunk of data to the program handle.
In case the given data is not a string, it is converted to a string before being written to the program's stdin. 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 proc.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 = popen("command", "w");
fp.write("Hello world!\n");