qjs:os Module - QuickJS-ng

The qjs:os module provides low-level operating system functionality including file I/O, process management, signals, timers, and worker threads.

import * as os from 'qjs:os';

Most OS functions return 0 on success or a negative error code (-errno) on failure.

File Operations

`open(filename, flags, mode)`

Opens a file and returns a file descriptor.

string

required

Path to the file

number

required

Bitwise OR of open flags (see below)

number

default:"0o666"

File permissions (used when creating files)

number

File descriptor (non-negative) or negative error code

import * as os from 'qjs:os';
import * as std from 'qjs:std';

const fd = os.open('data.txt', os.O_RDWR | os.O_CREAT, 0o644);
if (fd < 0) {
  console.log('Error:', std.strerror(-fd));
} else {
  // Use file descriptor
  os.close(fd);
}

Open Flags

os.O_RDONLY - Read-only
os.O_WRONLY - Write-only
os.O_RDWR - Read and write
os.O_APPEND - Append mode
os.O_CREAT - Create file if it doesn’t exist
os.O_EXCL - Fail if file exists (used with O_CREAT)
os.O_TRUNC - Truncate file to zero length
os.O_TEXT - Text mode (Windows only)

`close(fd)`

Closes a file descriptor.

number

required

File descriptor to close

number

Returns 0 on success or -errno on error

os.close(fd);

`seek(fd, offset, whence)`

Seeks to a position in the file.

number

required

File descriptor

number | BigInt

required

Byte offset. Use BigInt for large files.

number

required

Reference point: std.SEEK_SET, std.SEEK_CUR, or std.SEEK_END

number | BigInt

New file position, or negative error code. Returns BigInt if offset was BigInt.

import * as std from 'qjs:std';

// Seek to end of file
const size = os.seek(fd, 0, std.SEEK_END);

// Seek to beginning
os.seek(fd, 0, std.SEEK_SET);

`read(fd, buffer, offset, length)`

Reads data from a file descriptor into an ArrayBuffer.

number

required

File descriptor

ArrayBuffer

required

Destination buffer

number

required

Byte offset in buffer to start writing

number

required

Number of bytes to read

number

Number of bytes read, or negative error code

const buffer = new ArrayBuffer(1024);
const bytesRead = os.read(fd, buffer, 0, 1024);
if (bytesRead < 0) {
  console.log('Read error');
}

`write(fd, buffer, offset, length)`

Writes data from an ArrayBuffer to a file descriptor.

number

required

File descriptor

ArrayBuffer

required

Source buffer

number

required

Byte offset in buffer to start reading

number

required

Number of bytes to write

number

Number of bytes written, or negative error code

const buffer = new Uint8Array([72, 101, 108, 108, 111]).buffer;
const bytesWritten = os.write(fd, buffer, 0, 5);

File System Operations

`remove(filename)`

Deletes a file.

string

required

Path to file to remove

number

Returns 0 on success or -errno on error

const ret = os.remove('temp.txt');
if (ret !== 0) {
  console.log('Failed to remove file');
}

`rename(oldname, newname)`

Renames or moves a file.

string

required

Current path

string

required

New path

number

Returns 0 on success or -errno on error

os.rename('old.txt', 'new.txt');

`realpath(path)`

Resolves the canonical absolute pathname.

string

required

Path to resolve

[string, number]

Array containing [absolutePath, errorCode]. Check if errorCode is 0.

const [absPath, err] = os.realpath('../file.txt');
if (err === 0) {
  console.log('Absolute path:', absPath);
}

`getcwd()`

Returns the current working directory.

[string, number]

Array containing [path, errorCode]

const [cwd, err] = os.getcwd();
if (err === 0) {
  console.log('Current directory:', cwd);
}

`exePath()`

Returns the full path of the current executable.

string | undefined

Executable path or undefined if not available/supported

const exe = os.exePath();
console.log('Running from:', exe);

`chdir(path)`

Changes the current working directory.

string

required

New directory path

number

Returns 0 on success or -errno on error

os.chdir('/tmp');

`mkdir(path, mode)`

Creates a directory.

string

required

Directory path to create

number

default:"0o777"

Directory permissions

number

Returns 0 on success or -errno on error

os.mkdir('new_dir', 0o755);

`mkdtemp(pattern)`

Creates a temporary directory with a unique name.

string

default:"tmpXXXXXX"

Pattern where XXXXXX is replaced with random characters. Must end with XXXXXX.

[string, number]

Array containing [path, errorCode]. Directory is created with mode 0o700.

const [tmpDir, err] = os.mkdtemp('myapp-XXXXXX');
if (err === 0) {
  console.log('Created temp dir:', tmpDir);
}

Not available on Windows and WASI.

`mkstemp(pattern)`

Creates a temporary file with a unique name and opens it.

string

default:"tmpXXXXXX"

Pattern where XXXXXX is replaced with random characters. Must end with XXXXXX.

[string, number]

Array containing [path, fd] where fd is the file descriptor or negative error code.

const [tmpFile, fd] = os.mkstemp('data-XXXXXX');
if (fd >= 0) {
  // Use file descriptor
  const f = std.fdopen(fd, 'w+');
  f.puts('temp data');
  f.close();
  
  // File is NOT automatically deleted (unlike std.tmpfile)
  os.remove(tmpFile);
}

Not available on Windows and WASI. Unlike std.tmpfile(), the file is not automatically deleted.

`stat(path)` / `lstat(path)`

Returns file status information.

string

required

File path

[object, number]

Array containing [statObject, errorCode]. The stat object contains:

dev - Device ID
ino - Inode number
mode - File mode/permissions
nlink - Number of hard links
uid - User ID
gid - Group ID
rdev - Device ID (if special file)
size - File size in bytes
blocks - Number of blocks allocated
atime - Last access time (milliseconds since epoch)
mtime - Last modification time (milliseconds since epoch)
ctime - Last status change time (milliseconds since epoch)

const [st, err] = os.stat('file.txt');
if (err === 0) {
  console.log('Size:', st.size);
  console.log('Modified:', new Date(st.mtime));
  
  // Check if regular file
  if ((st.mode & os.S_IFMT) === os.S_IFREG) {
    console.log('Regular file');
  }
}

lstat() returns information about the link itself for symbolic links, while stat() follows the link.

File Mode Constants

os.S_IFMT - File type mask
os.S_IFIFO - FIFO (named pipe)
os.S_IFCHR - Character device
os.S_IFDIR - Directory
os.S_IFBLK - Block device
os.S_IFREG - Regular file
os.S_IFSOCK - Socket
os.S_IFLNK - Symbolic link
os.S_ISGID - Set-group-ID bit
os.S_ISUID - Set-user-ID bit

`utimes(path, atime, mtime)`

Changes file access and modification times.

string

required

File path

number

required

Access time in milliseconds since epoch

number

required

Modification time in milliseconds since epoch

number

Returns 0 on success or -errno on error

const now = Date.now();
os.utimes('file.txt', now, now);

`symlink(target, linkpath)`

Creates a symbolic link.

string

required

Target path (what the link points to)

string

required

Path of the symbolic link to create

number

Returns 0 on success or -errno on error

os.symlink('/usr/bin/node', '/usr/local/bin/node');

`readlink(path)`

Reads the target of a symbolic link.

string

required

Path to symbolic link

[string, number]

Array containing [target, errorCode]

const [target, err] = os.readlink('/usr/bin/node');
if (err === 0) {
  console.log('Link points to:', target);
}

`readdir(path)`

Reads directory contents.

string

required

Directory path

[string[], number]

Array containing [entries, errorCode]. Entries include ”.” and ”..” if successful.

const [files, err] = os.readdir('.');
if (err === 0) {
  for (const file of files) {
    if (file !== '.' && file !== '..') {
      console.log(file);
    }
  }
}

TTY Functions

`isatty(fd)`

Checks if a file descriptor is a terminal.

number

required

File descriptor

boolean

True if fd is a TTY

if (os.isatty(0)) {
  console.log('stdin is a terminal');
}

`ttyGetWinSize(fd)`

Returns the terminal window size.

number

required

TTY file descriptor

[number, number] | null

Array [width, height] or null if not available

const size = os.ttyGetWinSize(1);
if (size) {
  console.log(`Terminal size: ${size[0]}x${size[1]}`);
}

`ttySetRaw(fd)`

Sets the terminal to raw mode (no line buffering, no echo).

number

required

TTY file descriptor

os.ttySetRaw(0); // Set stdin to raw mode

Process Management

`exec(args, options)`

Executes a new process.

string[]

required

Command and arguments. First element is the command.

object

Optional configuration

boolean

default:true

If true, waits for process to complete and returns exit code. If false, returns process ID.

boolean

default:true

If true, searches for executable in PATH

string

Executable path (defaults to args[0])

string

Working directory for the process

number

File descriptor to use for stdin

number

File descriptor to use for stdout

number

File descriptor to use for stderr

object

Environment variables as key-value pairs

number

Set process UID (Unix only)

number

Set process GID (Unix only)

number[]

Supplementary group IDs (Unix only)

number

If blocking: exit code (positive) or negated signal number (negative). If non-blocking: process ID.

// Blocking execution
const exitCode = os.exec(['ls', '-l']);
console.log('Exit code:', exitCode);

// Non-blocking
const pid = os.exec(['sleep', '10'], { block: false });
console.log('Started process:', pid);

// Capture output
const [readFd, writeFd] = os.pipe();
os.exec(['echo', 'hello'], { block: true, stdout: writeFd });
os.close(writeFd);

const buffer = new ArrayBuffer(100);
const n = os.read(readFd, buffer, 0, 100);
os.close(readFd);

`waitpid(pid, options)`

Waits for a child process to change state (Unix system call).

number

required

Process ID to wait for

number

required

Wait options (e.g., os.WNOHANG)

[number, number]

Array containing [ret, status]. ret contains -errno on error.

os.WNOHANG - Return immediately if no child has exited

`dup(fd)`

Duplicates a file descriptor.

number

required

File descriptor to duplicate

number

New file descriptor or negative error code

`dup2(oldfd, newfd)`

Duplicates a file descriptor to a specific descriptor number.

number

required

Source file descriptor

number

required

Target file descriptor number

number

Returns newfd on success or negative error code

`pipe()`

Creates a pipe for inter-process communication.

[number, number] | null

Array [readFd, writeFd] or null on error

const [readFd, writeFd] = os.pipe();
os.write(writeFd, new Uint8Array([1, 2, 3]).buffer, 0, 3);

const buffer = new ArrayBuffer(10);
os.read(readFd, buffer, 0, 10);

os.close(readFd);
os.close(writeFd);

Signals

`signal(signal, func)`

Registers a signal handler.

number

required

Signal number (e.g., os.SIGINT)

function | null | undefined

Handler function, null for default handler, or undefined to ignore signal

import * as os from 'qjs:os';

os.signal(os.SIGINT, () => {
  console.log('Caught SIGINT');
  std.exit(0);
});

Signal handlers can only be defined in the main thread, not in workers.

Signal Constants

os.SIGINT - Interrupt (Ctrl+C)
os.SIGABRT - Abort
os.SIGFPE - Floating point exception
os.SIGILL - Illegal instruction
os.SIGSEGV - Segmentation fault
os.SIGTERM - Termination request

`kill(pid, sig)`

Sends a signal to a process.

number

required

Process ID

number

required

Signal number

os.kill(pid, os.SIGTERM);

Asynchronous I/O

`setReadHandler(fd, func)`

Registers a callback for when data is available to read.

number

required

File descriptor

function | null

Callback function, or null to remove handler

os.setReadHandler(fd, () => {
  const buffer = new ArrayBuffer(1024);
  const n = os.read(fd, buffer, 0, 1024);
  console.log('Read', n, 'bytes');
});

Only one read handler per file descriptor is supported.

`setWriteHandler(fd, func)`

Registers a callback for when the file descriptor is ready for writing.

number

required

File descriptor

function | null

Callback function, or null to remove handler

os.setWriteHandler(fd, () => {
  const data = new Uint8Array([1, 2, 3]);
  os.write(fd, data.buffer, 0, 3);
  os.setWriteHandler(fd, null); // Remove handler
});

Timers

`sleep(delay_ms)`

Blocks for the specified duration (synchronous).

number

required

Delay in milliseconds

os.sleep(1000); // Sleep for 1 second

`sleepAsync(delay_ms)`

Asynchronously sleeps for the specified duration.

number

required

Delay in milliseconds

Promise<void>

Promise that resolves after the delay

await os.sleepAsync(500);
console.log('500ms elapsed');

`setTimeout(func, delay)`

Calls a function after a delay.

function

required

Function to call

number

required

Delay in milliseconds

number

Timer ID for use with clearTimeout

const timerId = os.setTimeout(() => {
  console.log('Timer fired');
}, 1000);

`clearTimeout(id)`

Cancels a timer.

number

required

Timer ID returned by setTimeout

const timerId = os.setTimeout(() => console.log('Never called'), 1000);
os.clearTimeout(timerId);

Platform Information

`os.platform`

string

Platform identifier: "linux", "darwin", "win32", or "js"

if (os.platform === 'win32') {
  console.log('Running on Windows');
}

Workers (Threads)

`Worker(module_filename)`

Creates a new worker thread with an API similar to Web Workers.

string

required

Path to the module to execute in the worker thread (relative to current script)

// main.js
import * as os from 'qjs:os';

const worker = new os.Worker('worker.js');

worker.onmessage = (msg) => {
  console.log('Received from worker:', msg.data);
};

worker.postMessage({ command: 'start' });

// worker.js
import * as os from 'qjs:os';

os.Worker.parent.onmessage = (msg) => {
  console.log('Worker received:', msg.data);
  os.Worker.parent.postMessage({ result: 'done' });
};

Workers are not supported on WASI. Nested workers are not supported.

Worker Static Properties

Worker

In a worker thread, represents the parent worker. Used to communicate with the parent.

Worker Instance Methods

`postMessage(msg)`

Sends a message to the worker.

any

required

Message to send. The message is cloned using structured clone algorithm. SharedArrayBuffer instances are shared.

worker.postMessage({ type: 'task', data: [1, 2, 3] });

// Sharing data with SharedArrayBuffer
const shared = new SharedArrayBuffer(1024);
worker.postMessage({ buffer: shared });

Worker Instance Properties

`onmessage`

Getter and setter for the message handler function.

function | null

Function called when a message is received. Receives an event object with a data property.

worker.onmessage = (event) => {
  console.log('Message:', event.data);
};

A worker thread is kept alive as long as there is at least one non-null onmessage handler.

Example: Parallel Processing

// main.js
import * as os from 'qjs:os';
import * as std from 'qjs:std';

const numWorkers = 4;
const workers = [];
let completedCount = 0;

for (let i = 0; i < numWorkers; i++) {
  const worker = new os.Worker('compute.js');
  
  worker.onmessage = (msg) => {
    console.log(`Worker ${i} result:`, msg.data);
    completedCount++;
    
    if (completedCount === numWorkers) {
      console.log('All workers completed');
      std.exit(0);
    }
  };
  
  worker.postMessage({ workerId: i, task: 'compute' });
  workers.push(worker);
}

// compute.js
import * as os from 'qjs:os';

os.Worker.parent.onmessage = (msg) => {
  const { workerId, task } = msg.data;
  
  // Perform computation
  let result = 0;
  for (let i = 0; i < 1000000; i++) {
    result += Math.sqrt(i);
  }
  
  os.Worker.parent.postMessage({
    workerId,
    result
  });
};

​File Operations

​open(filename, flags, mode)

​Open Flags

​close(fd)

​seek(fd, offset, whence)

​read(fd, buffer, offset, length)

​write(fd, buffer, offset, length)

​File System Operations

​remove(filename)

​rename(oldname, newname)

​realpath(path)

​getcwd()

​exePath()

​chdir(path)

​mkdir(path, mode)

​mkdtemp(pattern)

​mkstemp(pattern)

​stat(path) / lstat(path)

​File Mode Constants

​utimes(path, atime, mtime)

​symlink(target, linkpath)

​readlink(path)

​readdir(path)

​TTY Functions

​isatty(fd)

​ttyGetWinSize(fd)

​ttySetRaw(fd)

​Process Management

​exec(args, options)

​waitpid(pid, options)

​dup(fd)

​dup2(oldfd, newfd)

​pipe()

​Signals

​signal(signal, func)

​Signal Constants

​kill(pid, sig)

​Asynchronous I/O

​setReadHandler(fd, func)

​setWriteHandler(fd, func)

​Timers

​sleep(delay_ms)

​sleepAsync(delay_ms)

​setTimeout(func, delay)

​clearTimeout(id)

​Platform Information

​os.platform

​Workers (Threads)

​Worker(module_filename)

​Worker Static Properties

​Worker Instance Methods

​postMessage(msg)

​Worker Instance Properties

​onmessage

​Example: Parallel Processing

File Operations

`open(filename, flags, mode)`

Open Flags

`close(fd)`

`seek(fd, offset, whence)`

`read(fd, buffer, offset, length)`

`write(fd, buffer, offset, length)`

File System Operations

`remove(filename)`

`rename(oldname, newname)`

`realpath(path)`

`getcwd()`

`exePath()`

`chdir(path)`

`mkdir(path, mode)`

`mkdtemp(pattern)`

`mkstemp(pattern)`

`stat(path)` / `lstat(path)`

File Mode Constants

`utimes(path, atime, mtime)`

`symlink(target, linkpath)`

`readlink(path)`

`readdir(path)`

TTY Functions

`isatty(fd)`

`ttyGetWinSize(fd)`

`ttySetRaw(fd)`

Process Management

`exec(args, options)`

`waitpid(pid, options)`

`dup(fd)`

`dup2(oldfd, newfd)`

`pipe()`

Signals

`signal(signal, func)`

Signal Constants

`kill(pid, sig)`

Asynchronous I/O

`setReadHandler(fd, func)`

`setWriteHandler(fd, func)`

Timers

`sleep(delay_ms)`

`sleepAsync(delay_ms)`

`setTimeout(func, delay)`

`clearTimeout(id)`

Platform Information

`os.platform`

Workers (Threads)

`Worker(module_filename)`

Worker Static Properties

Worker Instance Methods

`postMessage(msg)`

Worker Instance Properties

`onmessage`

Example: Parallel Processing