OS Module

(os/arch)

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

* :x86

* :x64

* :arm

* :aarch64

* :riscv32

* :riscv64

* :sparc

* :wasm

* :s390

* :s390x

* :unknown

(os/cd path)

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

(os/chmod path mode)

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.

(os/clock &opt source format)

Return the current time of the requested clock source.

The `source` argument selects the clock source to use, when not specified the default is `:realtime`:
- :realtime: Return the real (i.e., wall-clock) time. This clock is affected by discontinuous jumps in the system time
- :monotonic: Return the number of whole + fractional seconds since some fixed point in time. The clock is guaranteed to be non-decreasing in real time.
- :cputime: Return the CPU time consumed by this process (i.e. all threads in the process)
The `format` argument selects the type of output, when not specified the default is `:double`:
- :double: Return the number of seconds + fractional seconds as a double
- :int: Return the number of seconds as an integer
- :tuple: Return a 2 integer tuple [seconds, nanoseconds]

(os/compiler)

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

* :gcc

* :clang

* :msvc

* :unknown

(os/cpu-count &opt dflt)

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.

(os/cryptorand n &opt buf)

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

(os/cwd)

Returns the current working directory.

(os/date &opt time local)

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

(os/dir dir &opt array)

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.

(os/environ)

Get a copy of the OS environment table.

(os/execute args &opt flags env)

Execute a program on the system and return the exit code. `args` is an array/tuple of strings. The first string is the name of the program and the remainder are arguments passed to the program. `flags` is a keyword made from the following characters that modifies how the program executes:
* :e - enables passing an environment to the program. Without 'e', the current environment is inherited.
* :p - allows searching the current PATH for the program to execute. Without this flag, the first element of `args` must be an absolute path.
* :x - raises error if exit code is non-zero.
* :d - prevents the garbage collector terminating the program (if still running) and calling the equivalent of `os/proc-wait` (allows zombie processes).
`env` is a table/struct mapping environment variables to values. It can also contain the keys :in, :out, and :err, which allow redirecting stdio in the subprocess. :in, :out, and :err should be core/file or core/stream values. If core/stream values are used, the caller is responsible for ensuring pipes do not cause the program to block and deadlock.

(os/exit &opt x force)

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. If `force` is truthy will exit immediately and skip cleanup code.

(os/getenv variable &opt dflt)

Get the string value of an environment variable.

(os/isatty &opt file)

Returns true if `file` is a terminal. If `file` is not specified, it will default to standard output.

(os/link oldpath newpath &opt symlink)

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.

(os/lstat path &opt tab|key)

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

(os/mkdir path)

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.

(os/mktime date-struct &opt local)

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.

(os/open path &opt flags mode)

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

(os/perm-int bytes)

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

(os/perm-string int)

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`.

(os/pipe &opt flags)

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. `flags` is a keyword set of flags to disable non-blocking settings on the ends of the pipe. This may be desired if passing the pipe to a subprocess with `os/spawn`.

* :W - sets the writable end of the pipe to a blocking stream.
* :R - sets the readable end of the pipe to a blocking stream.

By default, both ends of the pipe are non-blocking for use with the `ev` module.

(os/posix-exec args &opt flags env)

Use the execvpe or execve system calls to replace the current process with an interface similar to os/execute. However, instead of creating a subprocess, the current process is replaced. Is not supported on Windows, and does not allow redirection of stdio.

(os/posix-fork)

Make a `fork` system call and create a new process. Return nil if in the new process, otherwise a core/process object (as returned by os/spawn). Not supported on all systems (POSIX only).

(os/proc-close proc)

Close pipes created for subprocess `proc` by `os/spawn` if they have not been closed. Then, if `proc` is not being waited for, wait. If this function waits, when `proc` completes, return the exit code of `proc`. Otherwise, return nil.

(os/proc-kill proc &opt wait signal)

Kill the subprocess `proc` by sending SIGKILL to it on POSIX systems, or by closing the process handle on Windows. If `proc` has already completed, raise an error. If `wait` is truthy, will wait for `proc` to complete and return the exit code (this will raise an error if `proc` is being waited for). Otherwise, return `proc`. If `signal` is provided, send it instead of SIGKILL. Signal keywords are named after their C counterparts but in lowercase with the leading SIG stripped. `signal` is ignored on Windows.

(os/proc-wait proc)

Suspend the current fiber until the subprocess `proc` completes. Once `proc` completes, return the exit code of `proc`. If called more than once on the same core/process value, will raise an error. When creating subprocesses using `os/spawn`, this function should be called on the returned value to avoid zombie processes.

(os/readlink path)

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

(os/realpath path)

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

(os/rename oldname newname)

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

(os/rm path)

Delete a file. Returns nil.

(os/rmdir path)

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

(os/setenv variable value)

Set an environment variable.

(os/setlocale &opt locale category)

Set the system locale, which affects how dates and numbers are formatted. Passing nil to locale will return the current locale. Category can be one of:

 * :all (default)
 * :collate
 * :ctype
 * :monetary
 * :numeric
 * :time

Returns the new locale if set successfully, otherwise nil. Note that this will affect other functions such as `os/strftime` and even `printf`.

(os/shell str)

Pass a command string str directly to the system shell.

(os/sigaction which &opt handler interrupt-interpreter)

Add a signal handler for a given action. Use nil for the `handler` argument to remove a signal handler. All signal handlers are the same as supported by `os/proc-kill`.

(os/sleep n)

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

(os/spawn args &opt flags env)

Execute a program on the system and return a core/process value representing the spawned subprocess. Takes the same arguments as `os/execute` but does not wait for the subprocess to complete. Unlike `os/execute`, the value `:pipe` can be used for :in, :out and :err keys in `env`. If used, the returned core/process will have a writable stream in the :in field and readable streams in the :out and :err fields. On non-Windows systems, the subprocess PID will be in the :pid field. The caller is responsible for waiting on the process (e.g. by calling `os/proc-wait` on the returned core/process value) to avoid creating zombie process. After the subprocess completes, the exit value is in the :return-code field. If `flags` includes 'x', a non-zero exit code will cause a waiting fiber to raise an error. The use of `:pipe` may fail if there are too many active file descriptors. The caller is responsible for closing pipes created by `:pipe` (either individually or using `os/proc-close`). Similar to `os/execute`, the caller is responsible for ensuring pipes do not cause the program to block and deadlock.

(os/stat path &opt tab|key)

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)

(os/strftime fmt &opt time local)

Format the given time as a string, or the current time if `time` is not given. The time is formatted according to the same rules as the ISO C89 function strftime(). The time is formatted in UTC unless `local` is truthy, in which case the date is formatted for the local timezone.

(os/symlink oldpath newpath)

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

(os/time)

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

(os/touch path &opt actime modtime)

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

(os/umask mask)

Set a new umask, returns the old umask.

(os/which)

Check the current operating system. Returns one of:

* :windows

* :mingw

* :cygwin

* :macos

* :web - Web assembly (emscripten)

* :linux

* :freebsd

* :openbsd

* :netbsd

* :dragonfly

* :bsd

* :posix - A POSIX compatible system (default)

May also return a custom keyword specified at build time.