nish:fs

Files and directories: read, write, rename, remove and list paths on the host's file system.

import {
  appendFileSync,
  createFileExclusiveSync,
  fileClose,
  fileOpen,
  fileReadAt,
  fileSize,
  isDirectorySync,
  mkdirSync,
  mkdirSyncMode,
  readFileBytesSync,
  readFileSync,
  readFileSyncOrNull,
  readdirSync,
  realpathSync,
  renameSync,
  statMtimeSync,
  unlinkSync,
  writeFileBytesSync,
  writeFileSync,
  writeFileSyncMode,
} from "nish:fs";
import { readFileSyncOrNull, writeFileSyncMode, renameSync } from "nish:fs";

const text = readFileSyncOrNull("config.json");
if (text !== null) {
  if (writeFileSyncMode("token.tmp", text, 0o600) >= 0) renameSync("token.tmp", "token");
}

Each export is the global of the same name, renamed: the compiler emits the same IR for either spelling. Paths are relative to the working directory. The calls that answer an i32 answer the same numbers under Node, where runtime/nish.mjs turns the error Node throws into -errno from its code (ERR_INVALID_ARG_VALUE, Node's refusal of a NUL in a path, is -22).

A wasm32 build has none of these, and a WASI build answers -ENOSYS from the three that take a mode. Every negative errno is the platform's own, untranslated: the numbers shown here are Linux's, and another kernel's differ (ELOOP is -62 on Darwin), so compare against a negative result. A file longer than 2^31 - 1 bytes is one the read calls cannot read, in both number modes. A path that holds a NUL byte is refused as a missing path is.

Bytes and strings

A native string is never validated as UTF-8, so writeFileSync and appendFileSync send its bytes as they are; under the prelude and under --emit-ts a string is UTF-16 and a byte above 127 does not survive. readFileBytesSync and writeFileBytesSync move a u8[] unchanged on every host and are the route for bytes that are not text.

Atomic replacement

Write a temporary beside the target, then renameSync it over: a reader sees the old file or the new one and never neither. writeFileSyncMode writes in place, so a secret that replaces another goes through the same temporary and rename.

The rules: https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#file-io and https://github.com/amritk/nish/blob/main/docs/LANGUAGE.md#directories-and-subprocesses

Functions

appendFileSync

Create the file or append to it, and write data; a statement, not a value. A symbolic link as the last component of path is refused, as for writeFileSync.

const appendFileSync: (path: string, data: string) => void
pathstringrequired

The file to append to.

datastringrequired

The bytes of the string, sent as they are.

createFileExclusiveSync

O_CREAT|O_EXCL: create path at exactly mode, set as for writeFileSyncMode, and write data. Exactly one of any number of processes racing for one path wins, so it is a lock file: create it, and unlinkSync it to release. A winner whose write then fails removes the file before it answers, so a failed create never leaves a half-written lock behind. Never a panic.

const createFileExclusiveSync: (
  path: string,
  data: string,
  mode: i32,
) => i32
pathstringrequired

The file to create.

datastringrequired

The bytes of the string, sent as they are.

modei32required

The file's mode, 0..0o777, as for writeFileSyncMode.

returnsi32

The length written, -17 EEXIST when any name is already at path (a dangling symbolic link included, which is never followed), or another negative errno as for writeFileSyncMode.

fileClose

Close a descriptor fileOpen gave; close it once.

const fileClose: (fd: i32) => i32
fdi32required

A descriptor from fileOpen.

returnsi32

0, or a negative errno (-9 EBADF).

fileOpen

Open a regular file to read a window at a time: read-only, close-on-exec and non-blocking. A directory is -21, any other kind that is not a regular file -22. Close it with fileClose in a finally.

const fileOpen: (path: string) => i32
pathstringrequired

The file to open.

returnsi32

A descriptor (>= 0), or the negated Linux errno: -2 ENOENT, -13 EACCES, -20 ENOTDIR, -21 EISDIR, -22 for a FIFO or device, -6 ENXIO for a socket, -23 ENFILE, -24 EMFILE, -36 ENAMETOOLONG, -40 ELOOP; anything else is -5 EIO.

fileReadAt

Read up to len bytes from file offset pos into buf[off .. off + len) (pread). The window panics as buf.slice does when it falls outside buf; the array is never grown.

const fileReadAt: (
  fd: i32,
  buf: u8[],
  off: i32,
  len: i32,
  pos: i64,
) => i32
fdi32required

A descriptor from fileOpen.

bufu8[]required

The array the bytes land in.

offi32required

Where in buf the first byte lands.

leni32required

The most bytes to read.

posi64required

The file offset, an i64.

returnsi32

The bytes read, 0 at end of file (and for a len of 0, even on a closed or negative descriptor), or a negative errno: -22 for a negative or overflowing pos, -9 for a closed or negative descriptor, -21 EISDIR, -29 ESPIPE; anything else is -5 EIO.

fileSize

The file's size in bytes now, from fstat.

const fileSize: (fd: i32) => i64
fdi32required

A descriptor from fileOpen.

returnsi64

The size, or a negative errno.

isDirectorySync

One stat of path. The answer can be stale by the time the caller acts on it: mkdirSync is still the call that decides whether a directory was made, and readFileSyncOrNull the way to read a file without racing a check against it.

const isDirectorySync: (path: string) => boolean
pathstringrequired

The path to ask about.

returnsboolean

true when a directory exists at path as the call runs; false for everything else, including a missing path, a plain file, a device node and a parent that cannot be searched.

mkdirSync

Create one directory at mode 0777 & ~umask. It is not recursive, exactly like Node's fs.mkdirSync(p) with no options, so a missing parent is a failure and not a reason to create it.

const mkdirSync: (path: string) => boolean
pathstringrequired

The directory to create.

returnsboolean

true when a directory exists at path once the call returns, whether this call created it or it was already there; false for every other outcome, a plain file at path included.

mkdirSyncMode

mkdir(2) of one level at mode. The kernel applies the process umask to mode: a 0o700 directory stays 0o700 under any umask that leaves the owner's bits, and a wider mode may come out narrower. An existing name keeps its mode, never changed. Never a panic.

const mkdirSyncMode: (path: string, mode: i32) => i32
pathstringrequired

The directory to create; its parent must exist.

modei32required

The directory's mode, 0..0o777; the sticky, setuid and setgid bits are refused.

returnsi32

0, or a negative errno: -17 EEXIST for a name already there, -2 ENOENT for a missing parent, -22 EINVAL for a mode outside 0..0o777 or a NUL in path.

readFileBytesSync

The file's bytes, as they are on disk: nothing assumes UTF-8, so a zero byte, a byte of 0x80 or above and an invalid sequence all come back unchanged. The array is an ordinary arena u8[] whose length is the file's size and equals its capacity. There is no exiting twin. Under Node the answer is Array.from(fs.readFileSync(path)) or null.

const readFileBytesSync: (path: string) => u8[] | null
pathstringrequired

The file to read.

returnsu8[] | null

The bytes, or null for exactly the paths readFileSyncOrNull answers null for.

readFileSync

Read the whole file as one arena string. A failure prints nish: cannot read <path> to stderr and exits 1; readFileSyncOrNull is the call that answers instead.

const readFileSync: (path: string) => string
pathstringrequired

The file to read.

returnsstring

The file's contents.

readFileSyncOrNull

The same read as readFileSync, answering null where that call exits, so a program can report the missing file itself and carry on. null when the path cannot be read as a file: missing, a directory, a parent that cannot be searched, a pipe with no length to ask for. It subsumes an existsSync and has no time-of-check race; narrow the result with if (text !== null). It answers null for exactly the paths readFileSync prints "cannot read" for.

const readFileSyncOrNull: (path: string) => string | null
pathstringrequired

The file to read.

returnsstring | null

The file's contents, or null when it cannot be read as a file.

readdirSync

The directory's entries, sorted ascending by bytes, without . and ..; every other dotfile is an entry. The sort makes a listing the same on every machine; it agrees with Node's .sort() for ASCII names and can differ for names that are not.

const readdirSync: (path: string) => string[] | null
pathstringrequired

The directory to list.

returnsstring[] | null

The sorted entries, an empty array for an empty directory, or null when the directory cannot be read at all (a missing path, a plain file, a parent that cannot be searched). A WASI build always answers null.

realpathSync

path with every symbolic link resolved and every ., .. and repeated separator removed. Every component but the last must exist for POSIX realpath to answer at all. The bytes are copied into the arena, so the result is an ordinary string; narrow it with if (p !== null).

const realpathSync: (path: string) => string | null
pathstringrequired

The path to resolve.

returnsstring | null

The absolute resolved path, or null when it does not resolve, which a path that does not exist is.

renameSync

rename(2): from takes the name to, replacing a file already there in one step, so a reader sees the old file or the new one and never neither. Nothing is copied across file systems: write the temporary in the target's directory. Never a panic.

const renameSync: (from: string, to: string) => i32
fromstringrequired

The current name.

tostringrequired

The new name.

returnsi32

0, or a negative errno: -2 ENOENT for a missing from, -18 EXDEV when the two are on different file systems, -21 EISDIR or -20 ENOTDIR for a file against a directory, -22 EINVAL for a NUL in either path.

statMtimeSync

The path's modification time, following symbolic links, as Node's mtimeMs: milliseconds since the epoch with the sub-millisecond fraction kept.

const statMtimeSync: (path: string) => f64
pathstringrequired

The path to stat.

returnsf64

The modification time, or NaN when the path cannot be stat'd (missing, or a parent that cannot be searched), which m !== m tests.

unlinkSync

unlink(2): remove the name, and a symbolic link itself rather than what it names. A directory is refused, not removed: there is no fallback to rmdir. Never a panic.

const unlinkSync: (path: string) => i32
pathstringrequired

The name to remove.

returnsi32

0, or a negative errno: -2 ENOENT for a missing path, -21 EISDIR for a directory on Linux or -1 EPERM where the kernel answers so, -22 EINVAL for a NUL in path.

writeFileBytesSync

Create or truncate the file at mode 0644 and write the array's bytes as they are: readFileBytesSync's other half. A symbolic link as the last component is refused, as for writeFileSync. Where writeFileSync exits, this answers, and it never panics.

const writeFileBytesSync: (
  path: string,
  bytes: readonly u8[],
) => i32
pathstringrequired

The file to write.

bytesreadonly u8[]required

The bytes to write.

returnsi32

bytes.length, or a negative errno: -2 ENOENT for a missing directory, -13 EACCES, -21 EISDIR, -40 ELOOP for the refused link, -22 EINVAL for a NUL in path.

writeFileSync

Create or truncate the file at mode 0644 and write data; a statement, not a value. A symbolic link as the last component of path is refused with nish: cannot write <path>, where Node follows it.

const writeFileSync: (path: string, data: string) => void
pathstringrequired

The file to write.

datastringrequired

The bytes of the string, sent as they are.

writeFileSyncMode

Create or truncate the file and write data, as writeFileSync does, with the file left at exactly mode (0o600 for a secret). The open passes mode and an fchmod(2) sets it before the first byte is written, so the umask cannot widen it, a file that already existed at 0644 is narrowed before it holds the new contents, and no reader that opens it afterwards finds the secret under the old mode. A descriptor opened before, while the file was wider, is not revoked and still reads what is written.

The file is truncated and written in place, not through a temporary: a crash or a failed write leaves it empty or partial, and a file this process may write but does not own is emptied before the mode change answers -1 EPERM. To replace a secret, write it to a temporary beside the target and renameSync it over. A symbolic link as the last component is refused with -40 ELOOP, its target untouched. Never a panic.

const writeFileSyncMode: (
  path: string,
  data: string,
  mode: i32,
) => i32
pathstringrequired

The file to write.

datastringrequired

The bytes of the string, sent as they are.

modei32required

The file's mode, 0..0o777; the setuid, setgid and sticky bits are refused, not applied.

returnsi32

The length written, or a negative errno: -22 EINVAL for a mode outside 0..0o777 or a NUL in path, -2 ENOENT for a missing directory, -13 EACCES, -40 ELOOP for the refused link, -1 EPERM as above.