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");
}
appendFileSync
Create the file or append to it, and write data; a statement, not a value.
createFileExclusiveSync
O_CREAT|O_EXCL: create path at exactly mode, set as for writeFileSyncMode, and write data.
fileClose
Close a descriptor fileOpen gave; close it once.
fileOpen
Open a regular file to read a window at a time: read-only, close-on-exec and non-blocking.
fileReadAt
Read up to len bytes from file offset pos into buf[off .. off + len) (pread).
fileSize
The file's size in bytes now, from fstat.
isDirectorySync
One stat of path.
mkdirSync
Create one directory at mode 0777 & ~umask.
mkdirSyncMode
mkdir(2) of one level at mode.
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.
readFileSync
Read the whole file as one arena string.
readFileSyncOrNull
The same read as readFileSync, answering null where that call exits, so a program can report the missing file itself and carry on.
readdirSync
The directory's entries, sorted ascending by bytes, without . and ..; every other dotfile is an entry.
realpathSync
path with every symbolic link resolved and every ., .. and repeated separator removed.
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.
statMtimeSync
The path's modification time, following symbolic links, as Node's mtimeMs: milliseconds since the epoch with the sub-millisecond fraction kept.
unlinkSync
unlink(2): remove the name, and a symbolic link itself rather than what it names.
writeFileBytesSync
Create or truncate the file at mode 0644 and write the array's bytes as they are: readFileBytesSync's other half.
writeFileSync
Create or truncate the file at mode 0644 and write data; a statement, not a value.
writeFileSyncMode
Create or truncate the file and write data, as writeFileSync does, with the file left at exactly mode (0o600 for a secret).
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
pathstringrequiredThe file to append to.
datastringrequiredThe 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
pathstringrequiredThe file to create.
datastringrequiredThe bytes of the string, sent as they are.
modei32requiredThe 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
fdi32requiredA descriptor from fileOpen.
returnsi320, 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
pathstringrequiredThe 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
fdi32requiredA descriptor from fileOpen.
bufu8[]requiredThe array the bytes land in.
offi32requiredWhere in buf the first byte lands.
leni32requiredThe most bytes to read.
posi64requiredThe 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
fdi32requiredA descriptor from fileOpen.
returnsi64The 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
pathstringrequiredThe 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
pathstringrequiredThe 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
pathstringrequiredThe 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
pathstringrequiredThe 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
pathstringrequiredThe file to read.
returnsstringThe 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
pathstringrequiredThe file to read.
returnsstring | nullThe 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
pathstringrequiredThe 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
pathstringrequiredThe 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
fromstringrequiredThe current name.
tostringrequiredThe 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
pathstringrequiredThe 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
pathstringrequiredThe 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
pathstringrequiredThe file to write.
bytesreadonly u8[]requiredThe 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
pathstringrequiredThe file to write.
datastringrequiredThe 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
pathstringrequiredThe file to write.
datastringrequiredThe 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.

