quickjs-done-nextgen/docs/docs/stdlib.md

---
sidebar_position: 5
---

# Standard library

The standard libary is provided as part of the `qjs` executable and the `quickjs-libc.c` source file
and it's not part of the core engine.

## Globals

### `argv0`

Provides the executable path.

### `scriptArgs`

Provides the command line arguments. The first argument is the script name.

### `print(...args)`

Print the arguments separated by spaces and a trailing newline.

### `console.log(...args)`

Same as `print()`.

### `navigator.userAgent`

Returns `quickjs-ng/<version>`.

### `gc()`

Shorthand for `std.gc()`.

## `qjs:bjson` module

### `bjson.write(obj, [flags])`

Serializes the given object into the QuickJS internal serialization format.
Returns an ArrayBuffer with the serialized data.

Supported flags:

- `WRITE_OBJ_BYTECODE`: allow serializing functions and modules
- `WRITE_OBJ_REFERENCE`: allow serializing object references
- `WRITE_OBJ_SAB`: allow serializing SharedArrayBuffer instances
- `WRITE_OBJ_STRIP_DEBUG`: strip debugging information when serializing
- `WRITE_OBJ_STRIP_SOURCE`: strip the source information when serializing

### `bjson.read(buf, [pos], [len], [flags])`

De-serialize the given ArrayBuffer (in QuickJS internal serialization format) back into a JavaScript value.

Supported flags:

- `READ_OBJ_BYTECODE`: allow de-serializing functions and modules
- `READ_OBJ_REFERENCE`: allow de-serializing object references
- `READ_OBJ_SAB`: allow de-serializing SharedArrayBuffer instances

## `qjs:os` module

The `os` module provides Operating System specific functions:

- low level file access
- signals
- timers
- basic asynchronous I/O
- workers (threads)

The OS functions usually return 0 if OK or an OS specific negative
error code.

### `open(filename, flags, mode = 0o666)`

Open a file. Return a handle or < 0 if error.

Supported flags:

- `O_RDONLY`
- `O_WRONLY`
- `O_RDWR`
- `O_APPEND`
- `O_CREAT`
- `O_EXCL`
- `O_TRUNC`

POSIX open flags.

- `O_TEXT`

(Windows specific). Open the file in text mode. The default is binary mode.

### `close(fd)`

Close the file handle `fd`.

### `seek(fd, offset, whence)`

Seek in the file. Use `std.SEEK_*` for
`whence`. `offset` is either a number or a BigInt. If
`offset` is a BigInt, a BigInt is returned too.

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

Read `length` bytes from the file handle `fd` to the
ArrayBuffer `buffer` at byte position `offset`.
Return the number of read bytes or < 0 if error.

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

Write `length` bytes to the file handle `fd` from the
ArrayBuffer `buffer` at byte position `offset`.
Return the number of written bytes or < 0 if error.

### `isatty(fd)`

Return `true` is `fd` is a TTY (terminal) handle.

### `ttyGetWinSize(fd)`

Return the TTY size as `[width, height]` or `null` if not available.

### `ttySetRaw(fd)`

Set the TTY in raw mode.

### `remove(filename)`

Remove a file. Return 0 if OK or `-errno`.

### `rename(oldname, newname)`

Rename a file. Return 0 if OK or `-errno`.

### `realpath(path)`

Return `[str, err]` where `str` is the canonicalized absolute
pathname of `path` and `err` the error code.

### `getcwd()`

Return `[str, err]` where `str` is the current working directory
and `err` the error code.

### `chdir(path)`

Change the current directory. Return 0 if OK or `-errno`.

### `mkdir(path, mode = 0o777)`

Create a directory at `path`. Return 0 if OK or `-errno`.

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

Return `[obj, err]` where `obj` is an object containing the
file status of `path`. `err` is the error code. The
following fields are defined in `obj`: `dev`, `ino`, `mode`, `nlink`,
`uid`, `gid`, `rdev`, `size`, `blocks`, `atime`, `mtime`, `ctime`. The times are
specified in milliseconds since 1970. `lstat()` is the same as
`stat()` excepts that it returns information about the link
itself.

- `S_IFMT`
- `S_IFIFO`
- `S_IFCHR`
- `S_IFDIR`
- `S_IFBLK`
- `S_IFREG`
- `S_IFSOCK`
- `S_IFLNK`
- `S_ISGID`
- `S_ISUID`

Constants to interpret the `mode` property returned by
`stat()`. They have the same value as in the C system header
`sys/stat.h`.

### `utimes(path, atime, mtime)`

Change the access and modification times of the file `path`. The
times are specified in milliseconds since 1970. Return 0 if OK or `-errno`.

### `symlink(target, linkpath)`

Create a link at `linkpath` containing the string `target`. Return 0 if OK or `-errno`.

### `readlink(path)`

Return `[str, err]` where `str` is the link target and `err`
the error code.

### `readdir(path)`

Return `[array, err]` where `array` is an array of strings
containing the filenames of the directory `path`. `err` is
the error code.

### `setReadHandler(fd, func)`

Add a read handler to the file handle `fd`. `func` is called
each time there is data pending for `fd`. A single read handler
per file handle is supported. Use `func = null` to remove the
handler.

### `setWriteHandler(fd, func)`

Add a write handler to the file handle `fd`. `func` is
called each time data can be written to `fd`. A single write
handler per file handle is supported. Use `func = null` to remove
the handler.

### `signal(signal, func)`

Call the function `func` when the signal `signal`
happens. Only a single handler per signal number is supported. Use
`null` to set the default handler or `undefined` to ignore
the signal. Signal handlers can only be defined in the main thread.

- `SIGINT`
- `SIGABRT`
- `SIGFPE`
- `SIGILL`
- `SIGSEGV`
- `SIGTERM`

POSIX signal numbers.

### `kill(pid, sig)`

Send the signal `sig` to the process `pid`.

### `exec(args[, options])`

Execute a process with the arguments `args`. `options` is an
object containing optional parameters:

- `block` - Boolean (default = true). If true, wait until the process is
  terminated. In this case, `exec` return the exit code if positive
  or the negated signal number if the process was interrupted by a
  signal. If false, do not block and return the process id of the child.
- `usePath` - Boolean (default = true). If true, the file is searched in the
  `PATH` environment variable.
- `file` - String (default = `args[0]`). Set the file to be executed.
- `cwd` - String. If present, set the working directory of the new process.
- `stdin`, `stdout`, `stderr` - If present, set the handle in the child for stdin, stdout or stderr.
- `env` - Object. If present, set the process environment from the object
  key-value pairs. Otherwise use the same environment as the current
  process.
- `uid` - Integer. If present, the process uid with `setuid`.
- `gid` - Integer. If present, the process gid with `setgid`.

### `waitpid(pid, options)`

`waitpid` Unix system call. Return the array `[ret, status]`.
`ret` contains `-errno` in case of error.

- `WNOHANG`

Constant for the `options` argument of `waitpid`.

### `dup(fd)`

`dup` Unix system call.

### `dup2(oldfd, newfd)`

`dup2` Unix system call.

### `pipe()`

`pipe` Unix system call. Return two handles as `[read_fd, write_fd]` or null in case of error.

### `sleep(delay_ms)`

Sleep during `delay_ms` milliseconds.

### `sleepAsync(delay_ms)`

Asynchronouse sleep during `delay_ms` milliseconds. Returns a promise. Example:

```js
await os.sleepAsync(500);
```

### `setTimeout(func, delay)`

Call the function `func` after `delay` ms. Return a timer ID.

### `clearTimeout(id)`

Cancel a timer.

### `platform`

Return a string representing the platform: `"linux"`, `"darwin"`, `"win32"` or `"js"`.

### `Worker(module_filename)`

Constructor to create a new thread (worker) with an API close to that of
`WebWorkers`. `module_filename` is a string specifying the
module filename which is executed in the newly created thread. As for
dynamically imported module, it is relative to the current script or
module path. Threads normally don't share any data and communicate
between each other with messages. Nested workers are not supported. An
example is available in `tests/test_worker.js`.

The worker class has the following static properties:

- `parent` - In the created worker, `Worker.parent` represents the parent
  worker and is used to send or receive messages.

The worker instances have the following properties:
  
- `postMessage(msg)` - Send a message to the corresponding worker. `msg` is cloned in
  the destination worker using an algorithm similar to the `HTML`
  structured clone algorithm. `SharedArrayBuffer` are shared
  between workers.

- `onmessage` - Getter and setter. Set a function which is called each time a
  message is received. The function is called with a single
  argument. It is an object with a `data` property containing the
  received message. The thread is not terminated if there is at least
  one non `null` `onmessage` handler.

## `qjs:std` module

The `std` module provides wrappers to libc (`stdlib.h` and `stdio.h`) and a few other utilities.

### `exit(n)`

Exit the process.

### `evalScript(str, options = undefined)`

Evaluate the string `str` as a script (global
eval). `options` is an optional object containing the following
optional properties:

- `backtrace_barrier` - Boolean (default = false). If true, error backtraces do not list the
  stack frames below the evalScript.
- `async` - Boolean (default = false). If true, `await` is accepted in the
  script and a promise is returned. The promise is resolved with an
  object whose `value` property holds the value returned by the
  script.

### `loadScript(filename)`

Evaluate the file `filename` as a script (global eval).

### `loadFile(filename)`

Load the file `filename` and return it as a string assuming UTF-8
encoding. Return `null` in case of I/O error.

### `open(filename, flags, errorObj = undefined)`

Open a file (wrapper to the libc `fopen()`). Return the FILE
object or `null` in case of I/O error. If `errorObj` is not
undefined, set its `errno` property to the error code or to 0 if
no error occurred.

### `popen(command, flags, errorObj = undefined)`

Open a process by creating a pipe (wrapper to the libc
`popen()`). Return the FILE
object or `null` in case of I/O error. If `errorObj` is not
undefined, set its `errno` property to the error code or to 0 if
no error occurred.

### `fdopen(fd, flags, errorObj = undefined)`

Open a file from a file handle (wrapper to the libc
`fdopen()`). Return the FILE
object or null` in case of I/O error. If `errorObj` is not
undefined, set its `errno` property to the error code or to 0 if
no error occurred.

### `tmpfile(errorObj = undefined)`

Open a temporary file. Return the FILE
object or `null` in case of I/O error. If `errorObj` is not
undefined, set its `errno` property to the error code or to 0 if
no error occurred.

### `puts(str)`

Equivalent to `std.out.puts(str)`.

### `printf(fmt, ...args)`

Equivalent to `std.out.printf(fmt, ...args)`.

### `sprintf(fmt, ...args)`

Equivalent to the libc sprintf().

### `in`, `out`, `err`

Wrappers to the libc file `stdin`, `stdout`, `stderr`.

### `Error`

Enumeration object containing the integer value of common errors
(additional error codes may be defined):

- `EINVAL`
- `EIO`
- `EACCES`
- `EEXIST`
- `ENOSPC`
- `ENOSYS`
- `EBUSY`
- `ENOENT`
- `EPERM`
- `EPIPE`

### `strerror(errno)`

Return a string that describes the error `errno`.

### `gc()`

Manually invoke the cycle removal algorithm. The cycle removal
algorithm is automatically started when needed, so this function is
useful in case of specific memory constraints or for testing.

### `getenv(name)`

Return the value of the environment variable `name` or
`undefined` if it is not defined.

### `setenv(name, value)`

Set the value of the environment variable `name` to the string
`value`.

### `unsetenv(name)`

Delete the environment variable `name`.

### `getenviron()`

Return an object containing the environment variables as key-value pairs.

### `urlGet(url, options = undefined)`

Download `url` using the `curl` command line
utility. `options` is an optional object containing the following
optional properties:

- `binary` - Boolean (default = false). If true, the response is an ArrayBuffer
  instead of a string. When a string is returned, the data is assumed
  to be UTF-8 encoded.
- `full` - Boolean (default = false). If true, return the an object contains
  the properties `response` (response content),
  `responseHeaders` (headers separated by CRLF), `status`
  (status code). `response` is `null` is case of protocol or
  network error. If `full` is false, only the response is
  returned if the status is between 200 and 299. Otherwise `null`
  is returned.

### `FILE`

File object.

#### `close()`

Close the file. Return 0 if OK or `-errno` in case of I/O error.

#### `puts(str)`

Outputs the string with the UTF-8 encoding.

#### `printf(fmt, ...args)`

Formatted printf.

The same formats as the standard C library `printf` are
supported. Integer format types (e.g. `%d`) truncate the Numbers
or BigInts to 32 bits. Use the `l` modifier (e.g. `%ld`) to
truncate to 64 bits.

#### `flush()`

Flush the buffered file.

#### `seek(offset, whence)`

Seek to a give file position (whence is
`std.SEEK_*`). `offset` can be a number or a BigInt. Return
0 if OK or `-errno` in case of I/O error.

- `SEEK_SET`
- `SEEK_CUR`
- `SEEK_END`

Constants for seek().

#### `tell()`

Return the current file position.

#### `tello()`

Return the current file position as a BigInt.

#### `eof()`

Return true if end of file.

#### `fileno()`

Return the associated OS handle.

#### `error()`

Return true if there was an error.

#### `clearerr()`

Clear the error indication.

#### `read(buffer, position, length)`

Read `length` bytes from the file to the ArrayBuffer `buffer` at byte
position `position` (wrapper to the libc `fread`).

#### `write(buffer, position, length)`

Write `length` bytes to the file from the ArrayBuffer `buffer` at byte
position `position` (wrapper to the libc `fwrite`).

#### `getline()`

Return the next line from the file, assuming UTF-8 encoding, excluding
the trailing line feed.

#### `readAsString(max_size = undefined)`

Read `max_size` bytes from the file and return them as a string
assuming UTF-8 encoding. If `max_size` is not present, the file
is read up its end.

#### `getByte()`

Return the next byte from the file. Return -1 if the end of file is reached.

#### `putByte(c)`

Write one byte to the file.