OS Module

Check the ISA that janet was compiled for. Returns one of:

* :x86

* :x64

* :arm

* :aarch64

* :riscv32

* :riscv64

* :sparc

* :wasm

* :unknown

Change current directory to path. Returns nil on success, errors on failure.

Change file permissions, where `mode` is a permission string as returned by `os/perm-string`, or an integer as returned by `os/perm-int`. When `mode` is an integer, it is interpreted as a Unix permission value, best specified in octal, like 8r666 or 8r400. Windows will not differentiate between user, group, and other permissions, and thus will combine all of these permissions. Returns nil.

Return the number of whole + fractional seconds since some fixed point in time. The clock is guaranteed to be non-decreasing in real time.

Get the compiler used to compile the interpreter. Returns one of:

* :gcc

* :clang

* :msvc

* :unknown

Get an approximate number of CPUs available on for this process to use. If unable to get an approximation, will return a default value dflt.

Get or append `n` bytes of good quality random data provided by the OS. Returns a new buffer or `buf`.

Returns the current working directory.

Returns the given time as a date struct, or the current time if `time` is not given. Returns a struct with following key values. Note that all numbers are 0-indexed. Date is given in UTC unless `local` is truthy, in which case the date is formatted for the local timezone.

* :seconds - number of seconds [0-61]

* :minutes - number of minutes [0-59]

* :hours - number of hours [0-23]

* :month-day - day of month [0-30]

* :month - month of year [0, 11]

* :year - years since year 0 (e.g. 2019)

* :week-day - day of the week [0-6]

* :year-day - day of the year [0-365]

* :dst - if Day Light Savings is in effect

Iterate over files and subdirectories in a directory. Returns an array of paths parts, with only the file name or directory name and no prefix.

Get a copy of the OS environment table.

Execute a program on the system and pass it string arguments. `flags` is a keyword that modifies how the program will execute.
* :e - enables passing an environment to the program. Without :e, the current environment is inherited.
* :p - allows searching the current PATH for the binary to execute. Without this flag, binaries must use absolute paths.
* :x - raise error if exit code is non-zero.
* :d - Don't try and terminate the process on garbage collection (allow spawning zombies).
`env` is a table or struct mapping environment variables to values. It can also contain the keys :in, :out, and :err, which allow redirecting stdio in the subprocess. These arguments should be core/file values. Returns the exit status of the program.

Exit from janet with an exit code equal to x. If x is not an integer, the exit with status equal the hash of x.

Get the string value of an environment variable.

Create a link at newpath that points to oldpath and returns nil. Iff symlink is truthy, creates a symlink. Iff symlink is falsey or not provided, creates a hard link. Does not work on Windows.

Like os/stat, but don't follow symlinks.

Create a new directory. The path will be relative to the current directory if relative, otherwise it will be an absolute path. Returns true if the directory was created, false if the directory already exists, and errors otherwise.

Get the broken down date-struct time expressed as the number of seconds since January 1, 1970, the Unix epoch. Returns a real number. Date is given in UTC unless `local` is truthy, in which case the date is computed for the local timezone.

Inverse function to os/date.

Create a stream from a file, like the POSIX open system call. Returns a new stream. `mode` should be a file mode as passed to `os/chmod`, but only if the create flag is given. The default mode is 8r666. Allowed flags are as follows:

 * :r - open this file for reading
 * :w - open this file for writing
 * :c - create a new file (O\_CREATE)
 * :e - fail if the file exists (O\_EXCL)
 * :t - shorten an existing file to length 0 (O\_TRUNC)

Posix-only flags:

 * :a - append to a file (O\_APPEND)
 * :x - O\_SYNC
 * :C - O\_NOCTTY

Windows-only flags:

 * :R - share reads (FILE\_SHARE\_READ)
 * :W - share writes (FILE\_SHARE\_WRITE)
  * :D - share deletes (FILE\_SHARE\_DELETE)
  * :H - FILE\_ATTRIBUTE\_HIDDEN
  * :O - FILE\_ATTRIBUTE\_READONLY
  * :F - FILE\_ATTRIBUTE\_OFFLINE
  * :T - FILE\_ATTRIBUTE\_TEMPORARY
  * :d - FILE\_FLAG\_DELETE\_ON\_CLOSE
  * :b - FILE\_FLAG\_NO\_BUFFERING

Parse a 9-character permission string and return an integer that can be used by chmod.

Convert a Unix octal permission value from a permission integer as returned by `os/stat` to a human readable string, that follows the formatting of Unix tools like `ls`. Returns the string as a 9-character string of r, w, x and - characters. Does not include the file/directory/symlink character as rendered by `ls`.

Create a readable stream and a writable stream that are connected. Returns a two-element tuple where the first element is a readable stream and the second element is the writable stream.

Wait on a process if it has not been waited on, and close pipes created by `os/spawn` if they have not been closed. Returns nil.

Kill a subprocess by sending SIGKILL to it on posix systems, or by closing the process handle on windows. If `wait` is truthy, will wait for the process to finish and returns the exit code. Otherwise, returns `proc`.

Block until the subprocess completes. Returns the subprocess return code.

Read the contents of a symbolic link. Does not work on Windows.

Get the absolute path for a given path, following ../, ./, and symlinks. Returns an absolute path as a string.

Rename a file on disk to a new path. Returns nil.

Delete a file. Returns nil.

Delete a directory. The directory must be empty to succeed.

Set an environment variable.

Pass a command string str directly to the system shell.

Suspend the program for `n` seconds. `n` can be a real number. Returns nil.

Execute a program on the system and return a handle to the process. Otherwise, takes the same arguments as `os/execute`. Does not wait for the process. For each of the :in, :out, and :err keys to the `env` argument, one can also pass in the keyword `:pipe` to get streams for standard IO of the subprocess that can be read from and written to. The returned value `proc` has the fields :in, :out, :err, :return-code, and the additional field :pid on unix-like platforms. Use `(os/proc-wait proc)` to rejoin the subprocess or `(os/proc-kill proc)`.

Gets information about a file or directory. Returns a table if the second argument is a keyword, returns only that information from stat. If the file or directory does not exist, returns nil. The keys are:

* :dev - the device that the file is on

* :mode - the type of file, one of :file, :directory, :block, :character, :fifo, :socket, :link, or :other

* :int-permissions - A Unix permission integer like 8r744

* :permissions - A Unix permission string like "rwxr--r--"

* :uid - File uid

* :gid - File gid

* :nlink - number of links to file

* :rdev - Real device of file. 0 on Windows

* :size - size of file in bytes

* :blocks - number of blocks in file. 0 on Windows

* :blocksize - size of blocks in file. 0 on Windows

* :accessed - timestamp when file last accessed

* :changed - timestamp when file last changed (permissions changed)

* :modified - timestamp when file last modified (content changed)

Create a symlink from oldpath to newpath, returning nil. Same as `(os/link oldpath newpath true)`.

Get the current time expressed as the number of whole seconds since January 1, 1970, the Unix epoch. Returns a real number.

Update the access time and modification times for a file. By default, sets times to the current time.

Set a new umask, returns the old umask.

Check the current operating system. Returns one of:

* :windows

* :mingw

* :cygwin

* :macos

* :web - Web assembly (emscripten)

* :linux

* :freebsd

* :openbsd

* :netbsd

* :posix - A POSIX compatible system (default)

May also return a custom keyword specified at build time.